diff options
Diffstat (limited to 'docs/core/index.rst')
| -rw-r--r-- | docs/core/index.rst | 67 |
1 files changed, 43 insertions, 24 deletions
diff --git a/docs/core/index.rst b/docs/core/index.rst index b17a4320..84ac8fb4 100644 --- a/docs/core/index.rst +++ b/docs/core/index.rst @@ -12,11 +12,11 @@ The bitmask core daemon can be launched like this:: bitmaskd -The command-line program ``bitmaskctl`` and the GUI, will launch the +The command-line program ``bitmaskctl`` and the GUI will launch the daemon when needed. -Starting the API server -======================= +Starting the REST service +========================= If configured to do so, the bitmask core will expose all of the commands throught a REST API. In bitmaskd.cfg:: @@ -24,6 +24,45 @@ throught a REST API. In bitmaskd.cfg:: [services] web = True +API Authentication +================== + +By default, the resources in the API are protected by an authentication token. + +The rationale is that, since the Bitmask core can be used simultaneously by +several users, no single user should be able to interfere with others by +querying for sensible information or disrupting other users' interaction with +running services. + +Therefore, there's a small white list of resources that do not +need authentication, based on which is the subset of the API that needs to +provide functionality for the creation of new accounts (the first-run wizard +from the UI perspective). + +The local authentication token is sent back in the response for an +authentication call. + +This local session token is different from the remote SRP token, although both +are returned together. In the case that the remote SRP authentication with the +provider fails (or with no network connectivity), the backend **should** signal +the error but equally return a local authentication token (this is not +implemented yet, but needs to be done to support an offline mode of operation). + +To authenticate any request to the API, 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 , 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'} + Resources ========= @@ -252,7 +291,7 @@ JSON-encoded data to the POST. * ``invitecode`` *(optional)* - an optional invitecode, to be used if the provider requires it for creating a new account. * ``autoconf`` *(optional)* - whether to autoconfigure the provider, if - we don't have seen it before. + we have not seen it before. **Status codes**: * ``200`` - no error @@ -332,23 +371,3 @@ JSON-encoded data to the POST. Export keys for an user. -API Authentication -================== - -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'} - |