diff options
| -rw-r--r-- | docs/core/index.rst | 67 | ||||
| -rw-r--r-- | src/leap/bitmask/core/_session.py | 12 |
2 files changed, 48 insertions, 31 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'} - diff --git a/src/leap/bitmask/core/_session.py b/src/leap/bitmask/core/_session.py index 24070a82..9b22f154 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 |