: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 API server
=======================

If configured to do so, the bitmask core will expose all of the commands
throught a REST API. In bitmaskd.cfg::

  [services]
  web = True


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

.. _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**:
        * ``foo`` *(required)* - foo bar.
        * ``bar`` *(optional)* - foo bar.

  **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**:
        * ``foo`` *(required)* - foo bar.

.. _cmd_user_update:

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

  Update a given user.

.. _cmd_user_auth:

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

  Authenticate an user.

.. _cmd_user_logout:

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

  Logs out an user, and destroys its local session.

.. _cmd_keys_list:

/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.


API Authentication
==================

(TBD) Most of the resources in the API are protected by an authentication token.