6. Security#

QuasarDB employs state of the art security mechanisms that handle all aspects of a secure database cluster:

  • Authentication between clients and servers are done using public/private key authentication;

  • The communication between client and servers can optionally be encrypted using these keypairs;

  • Cluster-side, node-to-node communication can optionally be encrypted;

  • Granular privilege authorization ensures that users are able to perform a subset of operations on a set of resources.

Warning

QuasarDB does not employ full stream encryption by default. To enable it, see Encrypted communication.

6.1. Enable access-control#

Before we can continue setting up security controls, you must enable access control by setting the correct security configuration parameters.

6.2. Key management#

QuasarDB’s security mechanism uses public/private key authenitcation, and has four distinct types of files that manage these:

  • A cluster public key, typically located in /usr/share/qdb/cluster_public.key. This file is safe to be shared with anyone that wants to connect to the database.

  • A cluster private key, typically located in /etc/qdb/cluster_private.key. This file contains sensitive data and should never be shared with users, and kept in a safe place.

  • A file that contains data and metadata about all users that can access the QuasarDB daemon, typically located in /etc/qdb/users.txt. This file should not be shared with anyone.

  • For each user, a private security token is generated which they can use to authenticate against the database.

The cluster public key cluster_public.key, private key cluster_private.key and the user metdata file users.txt must be identically replicated and available on all QuasarDB nodes.

6.3. Cluster key generation#

A QuasarDB daemon node needs to have the cluster’s public and private key files in order to operate. If you installed QuasarDB through a package manager, it’s likely that these keys have already been generated. If this is not the case, or if you want more control over the process you can use the qdb_cluster_keygen tool to generate these keys:

$ qdb_cluster_keygen --output-public /usr/share/qdb/cluster_public.key --output-secret /etc/qdb/cluster_private.key

The cluster_private.key should be stored on each of the QuasarDB nodes, and corresponds to the global.security.cluster_private_file configuration parameter in the QuasarDB configuration file. This is a sensitive file that should never be shared with anyone.

The cluster_public.key contains the public key and should be shared with each of the users that wishes to connect to the QuasarDB daemon.

6.4. User management#

QuasarDB maintains user credentials using two different files:

  • The QuasarDB daemon maintains a file that contains data and metadata about all users that can access the database. This file must be identically replicated on all QuasarDB nodes, and is typically located at /etc/qdb/users.txt.

  • For each user, a private security token is generated which they can use to authenticate against the database.

To add a new user to the database, we can use the qdb_user_add tool to add a new user:

$ qdb_user_add --uid 1 --username analyst -p /etc/qdb/users.txt --privileges 16390 -s /tmp/analyst.key

This will add an entry for the user analyst, user id 1 and privileges 16390 (more information about privileges can be found later in this chapter). The file /etc/qdb/users.txt will be created if it does not yet exist, and should look similar to this after executing the command above:

{
  "users": [
     {
         "uid": 1,
         "username": "analyst",
         "disabled": false,
         "superuser": false,
         "default_privileges": 16390,
         "public_key": "Poy32C8p4wvIreUcKA5+xiFkfPX8Plb3e6NERIDPvoiA="
     }
  ]
}

The users.txt should be stored on each of the QuasarDB nodes, and corresponds to the global.security.user_list configuration parameter in the QuasarDB configuration file.

In addition to this, there should be a file called /tmp/analyst.key, which contains the security token the user can use to authenticate against the database.

6.5. Authentication#

Authentication is the process of establishing the identity of a client. When security is enabled, QuasarDB requires all clients to authenticate with the cluster in order to establish their identity.

In order to do this, a user needs to provide the following:

  • A username;

  • A user private key;

  • A cluster public key.

For the username and user private key, one can take a look at one of the user security files:

{
  "username": "analyst",
  "secret_key": "SlqrtVosIcR0Y/awboeHO/1G1HK7S4tIFiiJ6oXx1Wr0="
}

You can establish a secure connection using the QuasarDB shell as follows:

$ qdbsh --cluster-public-key /usr/share/qdb/cluster_public.key --user-security-file /path/to/my_private.key

If you want to establish a secure connection using one of the language APIs, please refer to the secure connection tutorial.

6.6. Authorization#

Authorization is the process of determining the privileges a user has on a certain resource. Authorization works in conjunction with authenitcation, as privileges are assigned based on a user’s identity.

6.6.1. Privileges#

A user’s privileges for a certain object are determined on two levels:

  • The default privileges assigned to a user with qdb_user_add;

  • Additional privileges for the user manually assigned to the table using Grant or Revoke.

Each privilege is a flag with a number, for which you can view an overview below. To combine several privileges into a single number, one simply add the codes of each of the privileges. For example, to assign the select, insert and set_transaction privileges, the calculation would be:

select (2) + insert (4) + set_transaction (16384) = 2 + 4 + 16384 = 16390

6.6.2. Reference#

Name

Code

Description

denied:

1

The absence of privileges. When this flag is present, all other privileges will be ignored.

select:

2

The right to select (read) information from an object.

insert:

4

The right to insert (add additional) information into an object.

update:

8

The right to update existing value(s) of an object.

delete:

16

The right to delete value(s) inside an object.

index:

32

The right to create or modify indexes of tables.

alter:

64

The right to alter the properties of an object.

create:

128

The right to create an object.

drop:

256

The right to delete an object.

grant:

512

The right to manage rights of an object.

user_manage:

1024

The right to manage users inside the system.

system:

2048

The right to execute cluster-wide commands such as purging the caches.

set_acl:

4096

The right to modify access control to entries.

get_acl:

8192

The right to read access control list of entries.

set_transaction:

16384

The right to commit or rollback a transaction.

6.7. Encrypted communication#

QuasarDB allows you to encrypt communication between client and server, including node-to-node communication. This is disabled by default, as there is a non-neglectible performance overhead in full stream encryption, and most deployments have secured L2/L3 communications anyway.

To enable full stream encryption, enable the global.security.encrypt_traffic in the security configuration parameters.

Note

Traffic is encrypted using AES GCM with a 256-bit key. It requires the AES-NI instructions or equivalent.

6.8. Access control#

In addition to default privileges, you can specify access control for every entry. The explicit access specification overrides the default privileges of the user.

You can use access control to:

  • Give more access than the default privileges

  • Give less access than the default privileges

Modifying access control requires the “set_acl” privilege.

To give explicit privileges to an entry use the GRANT query (see Grant) to remove privileges use the REVOKE query (see Revoke).

To improve performance, nodes will cache ACL information. The size and duration of the cache is configuration. This means that it may take up to the cache date validity for updated ACL information to propagate in the cluster.