summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorKali Kaneko (leap communications) <kali@leap.se>2016-12-12 03:11:56 +0100
committerKali Kaneko (leap communications) <kali@leap.se>2016-12-29 03:09:57 +0100
commit58eed37a06da111b8b22378ad2511e8a793b1c69 (patch)
treecd6a31f7cca3027aae47b8a853b78151ec93c51a /docs
parent4378cf0b0c454dd5de6d40a9bb59eef653a25a41 (diff)
[docs] add doc about authentication header
Diffstat (limited to 'docs')
-rw-r--r--docs/core/index.rst99
1 files changed, 59 insertions, 40 deletions
diff --git a/docs/core/index.rst b/docs/core/index.rst
index bd70d36..5b33d82 100644
--- a/docs/core/index.rst
+++ b/docs/core/index.rst
@@ -31,45 +31,48 @@ Resources
Following is a list of currently available resources and a brief description of
each one. For details click on the resource name.
-+-----------------------------------+---------------------------------+
-| Resource | Description |
-+===================================+=================================+
-| ``POST`` :ref:`cmd_core_version` | Get Bitmask Core Version Info |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_core_stats` | Get Stats about Bitmask Usage |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_core_status` | Get Bitmask Status |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_core_stop` | Stop Bitmask Core |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_prov_list` | List all providers |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_prov_create` | Create a new provider |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_prov_read` | Get info about a provider |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_prov_del` | Delete a given provider |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_user_list` | List all users |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_user_active` | Get active user |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_user_create` | Create a new user |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_user_update` | Update an user |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_user_auth` | Authenticate an user |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_user_logout` | End session for an user |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_keys_list` | Get all known keys for an user |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_keys_insert` | Insert a new key |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_keys_del` | Delete a given key |
-+-----------------------------------+---------------------------------+
-| ``POST`` :ref:`cmd_keys_export` | Export keys |
-+-----------------------------------+---------------------------------+
+**By default, all the resources need authentication**. An asterisk next to it
+means that it does not need an authentication header.
+
++------------------------------------+---------------------------------+
+| Resource | Description |
++====================================+=================================+
+| ``POST`` :ref:`cmd_core_version` * | Get Bitmask Core Version Info |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_core_stats` * | Get Stats about Bitmask Usage |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_core_status` | Get Bitmask Status |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_core_stop` | Stop Bitmask Core |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_prov_list` * | List all providers |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_prov_create` * | Create a new provider |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_prov_read` * | Get info about a provider |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_prov_del` | Delete a given provider |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_user_list` | List all users |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_user_active` | Get active user |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_user_create` * | Create a new user |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_user_update` | Update an user |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_user_auth` * | Authenticate an user |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_user_logout` | End session for an user |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_keys_list` | Get all known keys for an user |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_keys_insert` | Insert a new key |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_keys_del` | Delete a given key |
++------------------------------------+---------------------------------+
+| ``POST`` :ref:`cmd_keys_export` | Export keys |
++------------------------------------+---------------------------------+
.. _cmd_parameters:
@@ -306,4 +309,20 @@ JSON-encoded data to the POST.
API Authentication
==================
-(TBD) Most of the resources in the API are protected by an authentication token.
+Most of the resources in the API are protected by an authentication token.
+To authenticate the request, the ``Authentication`` header has to be added to
+it. You need to pass a ``Token`` field, with a value equal to the concatenation of
+the username and the local session token that you have received after the
+authentication call, base64-encoded::
+
+
+ $ curl -X POST localhost:7070/API/core/stop
+ $ Unauthorized
+
+ >>> import base64
+ >>> base64.b64encode('user@provider.org:52dac27fcf633b1dba58')
+ 'dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg='
+
+ $ curl -X POST localhost:7070/API/core/stop -H 'Authentication: Token dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg='
+ $ {'shutdown': 'ok'}
+