path: root/docs/core/index.rst

:LastChangedDate: $LastChangedDate$
:LastChangedRevision: $LastChangedRevision$
:LastChangedBy: $LastChangedBy$

.. _bitmask_core:

============
Bitmask Core
============

The bitmask core daemon can be launched like this::

  bitmaskd

The command-line program ``bitmaskctl`` and the GUI will launch the
daemon when needed.

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::

  [services]
  web = True


Global API Authentication
=========================

To avoid some kind of attacks, the Bitmask API is protected by a global
authentication token.

The JS API receives this value when the initial entrypoint is loaded for the
first time, in the anchor part of the url.

To authenticate any request to the API, the ``X-Bitmask-Auth`` header has to be
added to it, set to the single value that is initialized during the bitmask
deaemon startup::

  curl -X POST http://localhost:7070/API/mail/status
  unauthorized:bad auth token

  curl -X POST http://localhost:7070/API/mail/status -H 'X-Bitmask-Auth: fae20706aa4f4f98ac0e67996787a370'
  {"result": {"status": "on", "childrenStatus": {"smtp": {"status": "on", "error": null}, "imap": {"status": "on", "error": null}}, "error": null}, "error": null}

This token can be found in ``.config/leap/authtoken``


API Authentication (this section not implemented yet)
======================================================

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 ``Authorization`` 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 'Authorization: Token dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg='
   $ {'shutdown': 'ok'}


Resources
========= 

Following is a list of currently available resources and a brief description of
each one. For details click on the resource name.

**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`    | Change the user password        |
+------------------------------------+---------------------------------+
| ``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:

Passing parameters
------------------

In all the cases that need data passed as parameter, those will be passed as
JSON-encoded data to the POST.

.. _cmd_core_version:

/core/version
-------------
**POST /core/version**

  Get Bitmask Core Version Info

  **Example request**::

        curl -X POST localhost:7070/API/core/version 

 
  **Example response**::

   {
      "error": null,
      "result":
          {
             "version_core": "0.9.3+185.g59ee6c29.dirty"
          }
   }


.. _cmd_core_stats:

/core/stats
-----------
**POST /core/stats**

  Get Stats about Bitmask Usage

.. _cmd_core_status:

/core/status
------------
**POST /core/status**

  Get Bitmask status

.. _cmd_core_stop:

/core/stop
----------
**POST /core/stop**

  Stop Bitmask core (daemon shutdown).

.. _cmd_prov_list:

/bonafide/provider/list
-----------------------
**POST /bonafide/provider/list**

  List all known providers.

.. _cmd_prov_create:

/bonafide/provider/create
--------------------------
**POST /bonafide/provider**

  Create a new provider.

.. _cmd_prov_read:

/bonafide/provider/read
-----------------------
**POST /bonafide/provider/read**

  Get info about a given provider.

  **Example request**::

  
        curl -X POST localhost:7070/API/bonafide/provider/read -d '["dev.bitmask.net"]'

 
  **Example response**::

   {
   "error": null,         
        "result": {
        "api_uri": "https://api.dev.bitmask.net:4430",
        "api_version": "1",          
        "ca_cert_fingerprint": "SHA256: 0f17c033115f6b76ff67871872303ff65034efe7dd1b910062ca323eb4da5c7e",
        "ca_cert_uri": "https://dev.bitmask.net/ca.crt",
        "default_language": "es",
        "description": {               
            "en": "Bitmask is a project of LEAP",
        }, 
        "domain": "dev.bitmask.net",
        "enrollment_policy": "open",
        "languages": [
            "es"
        ],
        "name": {
            "en": "Bitmask"
        },
        "service": {
            "allow_anonymous": false,
            "allow_free": true,
            "allow_limited_bandwidth": false,
            "allow_paid": false,
            "allow_registration": true,
            "allow_unlimited_bandwidth": true,
            "bandwidth_limit": 102400,
            "default_service_level": 1,
            "levels": {
                "1": {
                    "description": "Please donate.",
                    "name": "free"
                }
            }
        },
        "services": [
            "mx",
            "openvpn"
        ]
    }
   }

 
  **Form parameters**:
        * ``domain`` *(required)* - domain to obtain the info for.

.. _cmd_prov_del:

/bonafide/provider/delete
-------------------------
**POST /bonafide/provider/delete**

  Delete a given provider.


.. _cmd_user_list:

/bonafide/user/list
-------------------
**POST /bonafide/user/list**

  List all the users known to the local backend. 

  **Form parameters**:

  **Status codes**:
        * ``200`` - no error

.. _cmd_user_active:

/bonafide/user/active
---------------------
**POST /bonafide/user/active**

  Get the active user.

.. _cmd_user_create:

/bonafide/user/create
---------------------
**POST /bonafide/user/create**

  Create a new user.

  **Form parameters**:
        * ``username`` *(required)* - in the form user@provider.
        * ``pass`` *(required)* - the username passphrase
        * ``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 have not seen it before.

  **Status codes**:
        * ``200`` - no error

.. _cmd_user_update:

/bonafide/user/update
---------------------
**POST /bonafide/user/update**

  Change the user password.

  **Form parameters**:
        * ``username`` *(required)* - in the form user@provider
        * ``oldpass`` *(required)* - current password
        * ``newpass`` *(required)* - new password

  **Status codes**:
        * ``200`` - no error

.. _cmd_user_auth:

/bonafide/user/authenticate
---------------------------
**POST /bonafide/user/authenticate**

  Authenticate an user.

  **Form parameters**:

        * ``username`` *(required)* - in the form user@provider
        * ``pass`` *(required)* - passphrase
        * ``autoconf`` *(optional)* - whether to autoconfigure the provider, if
          we don't have seen it before.

  **Status codes**:
        * ``200`` - no error

.. _cmd_user_logout:

/bonafide/user/logout
---------------------
**POST /bonafide/user/logout**

  Logs out an user, and destroys its local session.

.. _cmd_keys_list:

/mail/status
-----------------------
**POST /mail/status

  Get the status of the mail service

  **Example request**::


        curl -X POST localhost:7070/API/mail/status -d '["foobar@mail.bitmask.net"]'


  **Example response**::


   {
     "result": {
       "status": "on",
       "keys": "found",
       "unread": 5,
       "childrenStatus": {
         "keymanager": {
           "status": "on",
           "keys": "found",
           "error": null
         },
         "smtp": {
           "status": "on",
           "error": null
         },
         "incoming": {
           "status": "on",
           "unread": 5,
           "error": null
         },
         "imap": {
           "status": "on",
           "error": null
         }
       },
       "error": null
     },
     "error": null
   }


  **Form parameters**:
        * ``address`` *(required)* - the email address of the account.

  **Values**:

  The possible values for ``status`` are:
       * ``on``
       * ``off``
       * ``starting``
       * ``stopping``
       * ``failed``

  The possible values for the ``keys`` field are:
        * ``null`` - nothing is known about the private key status.
        * ``sync`` - syncing soledad to see if there is a private key.
        * ``generating`` - creating a new private key as none was found.
        * ``found`` - there is a valid private key in KeyManager.


.. _cmd_prov_del:

/keys/list
-------------------
**POST /keys/list**

  Get all keys for an user.

.. _cmd_keys_insert:

/keys/insert/
-------------------
**POST /keys/insert**

  Insert a new key for an user.

.. _cmd_keys_del:

/keys/delete/
-------------------
**POST /keys/delete**

  Delete a key for an user.

.. _cmd_keys_export:

/keys/export/
-------------------
**POST /keys/export**

  Export keys for an user.