summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/core/index.rst67
-rw-r--r--src/leap/bitmask/core/_session.py12
2 files changed, 48 insertions, 31 deletions
diff --git a/docs/core/index.rst b/docs/core/index.rst
index b17a432..84ac8fb 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'}
-
diff --git a/src/leap/bitmask/core/_session.py b/src/leap/bitmask/core/_session.py
index 24070a8..9b22f15 100644
--- a/src/leap/bitmask/core/_session.py
+++ b/src/leap/bitmask/core/_session.py
@@ -33,15 +33,15 @@ logger = Logger()
class SessionService(HookableService):
"""
- This service holds random local-session tokens, that will be use to protect
- the access to the API resources.
+ This service holds random local-session tokens, that will be used to
+ protect the access to the API resources.
These tokens are different from the (remote) SRP session tokens: the
- local-session tokens are ephimeral and generated by the local Bitmask
- deamon.
+ local-session tokens are also ephemeral, but generated by the local Bitmask
+ daemon.
Right now, they are generated when a soledad instance is successfully
- created. This might be subject to further discussion, but this is the
+ created. This might be subject to further discussion, but this is the
earliest moment in which we can decide if a user should be authenticated
locally: it means that the entered password is able to decrypt the local
store. In this way, we can protect the API resources even in the case that
@@ -65,6 +65,4 @@ class SessionService(HookableService):
def hook_on_new_soledad_instance(self, **kw):
user = kw['user']
session_token = binascii.hexlify(os.urandom(10))
- print '---------------------------------------------------'
- print "hook on new soledad instance!", user, session_token
self._tokens[user] = session_token