: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. **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` | 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 ================== 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'}