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 /core/version * Get Bitmask Core Version Info
POST /core/stats * Get Stats about Bitmask Usage
POST /core/status Get Bitmask Status
POST /core/stop Stop Bitmask Core
POST /bonafide/provider/list * List all providers
POST /bonafide/provider/create * Create a new provider
POST /bonafide/provider/read * Get info about a provider
POST cmd_prov_del Delete a given provider
POST /bonafide/user/list List all users
POST /bonafide/user/active Get active user
POST /bonafide/user/create * Create a new user
POST /bonafide/user/update Change the user password
POST /bonafide/user/authenticate * Authenticate an user
POST /bonafide/user/logout End session for an user
POST /mail/status Get all known keys for an user
POST /keys/insert/ Insert a new key
POST /keys/delete/ Delete a given key
POST /keys/export/ Export keys

Passing parameters

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

/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"
       }
}

/core/stats

POST /core/stats

Get Stats about Bitmask Usage

/core/status

POST /core/status

Get Bitmask status

/core/stop

POST /core/stop

Stop Bitmask core (daemon shutdown).

/bonafide/provider/list

POST /bonafide/provider/list

List all known providers.

/bonafide/provider/create

POST /bonafide/provider

Create a new provider.

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

/bonafide/provider/delete

POST /bonafide/provider/delete

Delete a given provider.

/bonafide/user/list

POST /bonafide/user/list

List all the users known to the local backend.

Form parameters:

Status codes:
  • 200 - no error

/bonafide/user/active

POST /bonafide/user/active

Get the active user.

/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

/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

/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

/bonafide/user/logout

POST /bonafide/user/logout

Logs out an user, and destroys its local session.

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

/keys/list

POST /keys/list

Get all keys for an user.

/keys/insert/

POST /keys/insert

Insert a new key for an user.

/keys/delete/

POST /keys/delete

Delete a key for an user.

/keys/export/

POST /keys/export

Export keys for an user.