p≡p JSON adapter
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

251 lines
8.4 KiB

  1. # p≡p JSON Server Adapter
  2. ## Introduction
  3. The p≡p JSON Server Adapter provides a REST-like jQuery-compatible API to
  4. connect with the p≡p engine. It is language-independent and can be used by
  5. any client.
  6. ## Getting started - build and run
  7. In order to use the p≡p JSON Server Adapter, you need to build and run it.
  8. Currently, Linux and OSX/macOS are supported, Windows is about to follow.
  9. ### Building on Linux
  10. The p≡p JSON Server Adapter can be build on Debian and Ubuntu. Other
  11. distributions should work, but are not yet officially supported.
  12. #### System requirements
  13. Debian 9 or Ubuntu 16.04. Newer versions should also work (file a bug report
  14. if not) but are not in our main focus, yet.
  15. #### Dependencies
  16. * C++ compiler: tested with g++ 4.8 and 4.9, and clang++ 2.8. Newer versions should work, too.
  17. * GNU make
  18. * libboost-thread-dev (tested with 1.58)
  19. * libboost-program-options-dev (tested with 1.58)
  20. * libboost-filesystem-dev (tested with 1.58)
  21. * libevent-dev 2.0.21 or 2.0.22 (or build from source, see below)
  22. * [p≡p Engine](https://letsencrypt.pep.foundation/trac/wiki/Basic%20Concepts%20of%20p%E2%89%A1p%20engine) (which needs gpgme-thread,
  23. a patched libetpan, libboost-system-dev)
  24. #### Build steps
  25. 1. Build [p≡p Engine](https://letsencrypt.pep.foundation/trac/wiki/Basic%20Concepts%20of%20p%E2%89%A1p%20engine)
  26. 2. Build [libevent](http://libevent.org/)
  27. * tested with version 2.0.21 and 2.0.22, newer versions should work, too. 2.1.x is not yet tested.
  28. * Can be configured without dependency to OpenSSL, because the JSON Server Adapter does not use SSL/TLS.
  29. * A user-install in $HOME/local/ is fine.
  30. 3. Edit the library and include paths server/Makefile so p≡p & libevent will be found
  31. 4. Run "make" in the server/ path
  32. ```
  33. cd server
  34. make
  35. ```
  36. ### Building on macOS
  37. The p≡p JSON Server Adapter can be built on OS X or macOS with MacPorts.
  38. #### System requirements
  39. * OS X or macOS
  40. #### Preconditions
  41. For compiling the p≡p JSON Server Adapter and its dependencies, make sure
  42. you have the LANG variable set.
  43. ```
  44. export LANG=en_US.UTF-8
  45. ```
  46. #### Dependencies
  47. The following dependencies need to be installed in order to be able to build
  48. the p≡p JSON Server Adapter.
  49. ##### MacPorts
  50. [Install MacPorts](https://www.macports.org/install.php) for your version of OS X/macOS.
  51. If MacPorts is already installed on your machine, but was installed by a
  52. different user, make sure your `PATH` variable is set as follows in
  53. `~/.profile`:
  54. ```
  55. export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
  56. ```
  57. Install dependencies packaged with MacPorts as follows.
  58. ```
  59. sudo port install openssl boost ossp-uuid
  60. ```
  61. ##### libevent
  62. Install [libevent](http://libevent.org/).
  63. ```
  64. cd libevent-2.0.22-stable
  65. export LDFLAGS=-L/opt/local
  66. export CFLAGS=-I/opt/local/include
  67. ./configure --prefix "$HOME"
  68. make
  69. make install
  70. ```
  71. #### Build steps
  72. 1. Install dependencies
  73. 2. Run "make" in the server/ path
  74. ```
  75. cd server
  76. make
  77. ```
  78. ### Running the pEp JSON Adapter
  79. 1. Run ./pep-json-server. This creates a file that is readable only by the
  80. current user (/tmp/pEp-json-token-${USER}) and contains the address and
  81. port the JSON adapter is listening on, normally 127.0.0.1:4223 and a
  82. "security-token" that must be given in each function call to authenticate
  83. you as the valid user.
  84. ```
  85. ./pep-json-server
  86. ```
  87. 2. Visit that address (normally http://127.0.0.1:4223/) in your
  88. JavaScript-enabled web browser to see the test JavaScript client.
  89. 3. Call any function ("version()" or "get_gpg_path()" should work just
  90. fine) with the correct security token.
  91. ## Using the p≡p JSON Adapter
  92. In the following section, you'll find background information on how to use
  93. the adapter and its functions.
  94. ### Session handling
  95. When using the p≡p engine, a session is needed to which any adapter can
  96. connect. The p≡p JSON Server Adapter automatically creates one session per
  97. HTTP client connection (and also closes that session automatically when the
  98. client connections is closed). Therefore, the client does not need to take
  99. care of the session management. However, the client has to set up a [HTTP
  100. persistent
  101. connection](https://en.wikipedia.org/wiki/HTTP_persistent_connection).
  102. ### API Principles
  103. All C data types are mapped the same way, so some day the JSON wrapper can
  104. be generated from the p≡p Engine header files (or the JSON wrapper and the
  105. p≡p engine header are both generated from a common interface description
  106. file).
  107. | C type | JSON mapping |
  108. |--|--|
  109. | `bool` | JSON boolean |
  110. | `int` | JSON decimal number |
  111. | `size_t` | JSON decimal number |
  112. | `char*` (representing a UTF-8-encoded NULL-terminated string | JSON string |
  113. | `char*` (representing a binary string | base64-encoded JSON string |
  114. | `enum` | either JSON decimal number or JSON object containing one decimal number as member |
  115. | `struct` | JSON object |
  116. | linked lists (e.g. `bloblist_t`, `stringlist_t`, `identity_list` etc.) | JSON array of their member data type (without the `next` pointer) |
  117. The parameter type PEP_SESSION is handled automatically by the JSON Server
  118. Adapter and the PEP_SESSION parameter is omitted from the JSON API.
  119. #### enum types
  120. Enum types are represented as JSON objects with one member, whose name is
  121. derived from the enum type name, holding the numeric value of the enum.
  122. Some enum types are still represented directly as JSON decimal number. It
  123. shall be changed in a future version of the JSON Adapter.
  124. #### String types
  125. The JSON Server Adapter does automatic memory management for string
  126. parameters. The current p≡p Engine's API distinguish between `const char*`
  127. parameters and `char*` parameters. `const char*` normally means: the
  128. "ownership" of the string remains at the caller, so the JSON Adapter frees
  129. the string automatically after the call. `char*` normally means: the
  130. "ownership" of the string goes to the Engine, so the JSON Adapter does _not_
  131. free string.
  132. If there are functions that have a different semantics the behavior of the
  133. JSON wrapper has to be changed.
  134. #### Parameter (value) restrictions
  135. Some API functions have restrictions on their parameter values. The JSON
  136. Adapter does not know these restrictions (because it does not know the
  137. semantics of the wrapped functions at all). So it is the client's
  138. responsibility to fulfill these parameter restrictions! Especially when
  139. there are restrictions that are checked with assert() within the p≡p Engine,
  140. it is impossible for the JSON Adapter to catch failed assertions - the
  141. Engine and the Adapter process will be terminated immediatetely when the
  142. Engine is compiled in debug mode (= with enabled assert() checking).
  143. Currently there are no range checks for numerical parameter types (e.g. a
  144. JSON decimal number can hold a bigger value than the `int` parameter type of
  145. a certain C function).
  146. ### API Reference
  147. An complete overview with all functions that are callable from the client
  148. can be found in the [API Reference](pEp JSON Server Adapter/API Reference).
  149. Most of the callable functions are functions from the C API of the p≡p
  150. Engine. They are described in detail, incl. pre- and post-conditions in
  151. the appropriate C header files of the Engine.
  152. ## Extending / customizing
  153. If you want to extend or customize the p≡p JSON Adapter, there are several
  154. rules and definitions to take into account.
  155. ### Definitions
  156. * The `FunctionMap function` in `json-adapter.cc` defines which functions
  157. are callable via the JSON-RPC interface. The existing entries show the
  158. syntax of that map.
  159. * For each type there must exist specializations of the template classes
  160. "In" (for input parameters) and "Out" (for output parameters).
  161. The linker will tell you, which specializations are needed.
  162. * The specializations for "generic types" are in `function_map.cc`.
  163. * The specializations for "p≡p-specific types" are in `pep-types.cc`.
  164. ## TODOs
  165. The following issues are planned but not yet implemented.
  166. * Windows build:
  167. * implement get_token_filename() for MS Windows (security-token.cc line 43)
  168. * do the Windows-specific stuff to build the software on Windows
  169. * Add unit tests
  170. * Fix the bugs that are found by the Unit tests, if any.
  171. * Generate all the tedious boiler plate code
  172. * the content of pep-types.cc
  173. * perhaps the FunctionMap 'function' in mt-server.cc
  174. * perhaps the JavaScript side of the HTML test page to ensure to be
  175. consistent with the server side in pep-types.cc
  176. * Adapt the "p≡p Transport API", when it is final. (either manually or by
  177. code generator, if ready)