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