Atakama Key Shard Server

Overview

Under certain circumstances, for example, automated batch processing, Atakama’s Key Shard Server (KSS) can be used instead of a mobile device to approve decryption events. The KSS can be deployed to approve requests based on preconfigured policies that are controlled by the administrator, thereby allowing intended operations to perform file decryptions. The KSS can also be deployed across an organization to allow end users to access encrypted files without the need to perform MofNops on their mobile devices.

 The KSS instance and its profile are used to directly support its intended functionality, which is to perform decryptions. The KSS cannot be used to share encrypted files with end users.

Our suggested minimum server requirements for the KSS are 4 cores @2.5 GHz with 8GB RAM.

Architecture & Deployment Example

Key Shard Server Deployment 

Initialization

The KSS is controlled via the Command Line Interface (CLI). 

Setup KSS Profile

Install and onboard Atakama on your workstation. The Atakama Profile on your workstation will be used to secure the backup key for the KSS. This Atakama Profile should have at least two mobile devices and at least five total devices (including the workstation). The more devices, the greater the redundancy for business continuity and disaster recovery purposes.

Setup KSS Backup Secure Folder

Create a Secure Folder where the KSS backup key will be stored. For redundancy, this file should be backed up to other locations. Existing data backup policies should be sufficient.

Configure the Policy

Define policies in the %localappdata%\Atakama\keyserver.yml file.

Enable the KSS

Shut down Atakama and run the following command in cmd or Powershell:

atakama keyserver create --backup-path [PATH] [--ignore-security-checks]

(e.g.: atakama keyserver create --backup-path %homepath%\Atakama\backup-key.txt)

If a previous version of Atakama is being used (Perplexing Puma of prior versions), Run this command instead:

atakama keyserver enable --backup-path [PATH] [--ignore-security-checks]

(e.g.: atakama keyserver enable --backup-path %homepath%\Atakama\backup-key.txt)

The backup path must be within the Atakama Vault in the Secure Folder intended to secure the KSS backup key.

The setup will require a minimum threshold of three (3) devices required to approve and five (5) total devices as part of the profile unless the --ignore-security-checks flag is passed.

If it's needed, the command keyserver save-backup-key [PATH] can create a new KSS backup key if the previous one is lost. The [Path] section in the command should specify the file that will be created.

E.G.: keyserver save-backup-key "%homepath%\backup-key.txt"

After initialization, the KSS ID should be output onto the screen. This ID is required to onboard users using the KSS.

WARNING: When using a virtualized server, do not save a KSS snapshot as a backup in case the primary KSS goes down. Atakama does not support backwards compatibility in this scenario and it could lead to possible loss of data.

Creating a KSS Cluster

In the Quantum Quetzalcoatl version of Atakama, The function of creating and connecting multiple keyshard server instances has been added, in order to cover higher demands on automated processes and backups. It's called "Cluster Mode". 

In this mode, the use of a shared MySQL database that must be properly available to all instances is required. The machine with the database and all the Keyshard server instances should be connected in the same network. 

All Keyshard Server instances that join the shared database will share the same Keyserver ID and provide the same services. If one instance goes offline, the other instances will help get MofNop requests resolved.

Database creation:

The creation of a database for KSS Cluster is required, and can be done by launching MySQL Command Line Client and executing the following commands:

create database cvfs;

create user '[User]'@'%' identified by '[Add password here]';

grant all privileges on *.* to '[User]'@'%' with grant option;

flush privileges;

quit;

Onboarding a new Keyserver with the shared database:

On another computer which it's connected to the shared database by using the same network, and has Atakama installed, run the following command in cmd or Powershell:

atakama keyserver create [--db-uri URI][--ignore-security-checks] (--ignore-security-checks is optional).

(e.g.: atakama keyserver create --db-uri "mysql:host=[IP ADDRESS from the machine with MySQL],port=3306,user=[User],password=[Password assigned to that user],database=cvfs").

 The KSS backup key should be created within %homepath%, and if it's required, the command keyserver save-backup-key [PATH] can create a new KSS backup key if the previous one is not to be found.

E.G.: keyserver save-backup-key "%homepath%\backup-key.txt"

The setup will require a minimum threshold of three (3) devices required to approve and five (5) total devices as part of the profile unless the --ignore-security-checks flag is passed.

Keyserver should now be enabled using MySQL. To confirm, check the MySQL “cvfs” Database and see that the tables are now populated with data. 

Keyserver Instance Initialization:

If a Keyshard Server Instance has been already created in a shared database, you can add new instances on different machines by installing atakama on those machines, add the Keyserver.yml from the first Keyshard Server Instance to %localappdata%/atakama , and use the following commands in cmd or Powershell:

 First, it's important for admins to activate the license using the command:

Atakama settings update-license [Add enterprise license key]

After adding a license, you can continue initializing by using:

Atakama keyserver initialize --db-uri [--db-uri URI]

(e.g.:  Atakama keyserver initialize --db-uri "mysql:host=[IP ADDRESS from the machine with MySQL],port=3306,user=[User],password=[Password assigned to that user],database=cvfs")

This event will require the MofNop approval from the 3 devices that were used to approve the first Keyshard server instance that created the database. 

After approving this MofNop request, a message "Keyshard server initialized: restarting Atakama" - message should be returned in the terminal, letting the user know this instance has joined the Keyshard Server Cluster.

Converting a non-cluster Keyshard Server to Cluster Mode:

Upgrading from non-cluster keyshard server to cluster mode is possible only for those keyshard servers using Quantum Quetzalcoatl. It's required to upgrade from prior versions of atakama to Quantum Quetzalcoatl version or newer versions to do this action.

Database creation is required for Cluster Mode: Keyserver must be connected to a shared databases in order to activate the cluster mode. 

Shutdown the server and proceed to execute the following command in a terminal (cmd or windows powershell):

keyserver clone-db [NEW_URI]

(e.g.: atakama keyserver clone-db "mysql:host=[IP ADDRESS from the machine with MySQL],port=3306,user=[User],password=[Password assigned to that user],database=cvfs"

Once this command line is executed, this keyserver will start using the shared database and the cluster mode will be activated. It should be possible to initialize additional Keyshard Server Instances.

End-User Deployment

Onboarding with the KSS

There are three options when onboarding end users with the KSS:

1. The KSS ID is included in the enterprise configuration file before the end user first launches Atakama.

2. The KSS ID is added to the end user’s local atakama.config before the end user first launches Atakama.

3. The end users initiates onboarding via the CLI using command:
   atakama profile keyserver-onboard --keyserver-id [ID].

With any of these options, onboarding the end user is automatic and without end user involvement. Once onboarded, the end user will have received:

1. An Atakama Profile with the default name, username@hostname, containing two devices -- the workstation and the KSS.

2. A personal Security Group.

3. Two default Secure Folders (disabled for non-administrator end users).

The end user may be prompted to configure additional Secure Folders after the onboarding depending on the enterprise configuration.

Sharing

Sharing within the KSS environment is similar to sharing when Atakama is deployed without a KSS. User profiles with access to the Secure Folder locations must still be verified and then granted access by the administrator. The KSS does not support granting access to other profiles, so each Secure Folder must contain at least one additional non-KSS profile.

Policy Management

KSS policies consist of a series or combination of rules and rule sets. A KSS policy is defined by a rule tree encoded in YAML (see example here). The rule tree is split into sections by request type. Each request type section contains one or more rule sets (the outer list) that define the approval behavior for that request type. If any of the rule sets evaluate to true, then the request is approved (i.e., the rule sets are OR-ed).

Rules

Rules are simple conditions evaluated to either true or false. Rules are the basic building blocks of policies.

The KSS includes several default rule plugins (full documentation here).

MetaRule

Basic rule for approving requests based on file name or file path.

ProfileThrottleRule

Basic rule for applying per-profile limits on approvals.

ProfileIdRule

Basic rule for exact match of profile ids.

TimeRangeRule

Basic rule for time ranges.

Rule Sets

Each rule set contains one or more rules (the inner list). Every rule in a rule set must evaluate to true for that rule set to evaluate to true (i.e., the rules are AND-ed). The type of rule is defined by rule. Other arguments are specific to the rule in question.

For a given request type, rule sets are evaluated in the order specified in the policy. Most organizations would likely prefer to set a more permissive rule set ahead of a more restrictive ones.

Default Auto-Approval Behavior

When not specified in the KSS policy, the following request types are automatically approved without restriction. When these request types appear in the policy, the policy exclusively defines that behavior:

• create_profile

• create_location.

Incompatible Request / Rule Combinations

The following is a list of request types and provided rules that are not applicable to that request type:

• create_profile

  • profile-id-rule

  • per-profile-throttle-rule

  • meta-rule

• create_location

  • meta-rule

  • search

  • meta-rule.
    

Changing KSS Policies

KSS policies can be changed by editing the keyserver.yml file. The changes can be loaded either by restarting Atakama or by using:
atakama keyserver policy --load

For rules with persistent data (e.g., per-profile-throttle-rule), whether the existing data is retained depends on the rule being recognized as the same in the second version of the policy. The default behavior will attempt to do this automatically, but will work as intended only when that rule’s rule_id is manually set.

For KSS Clusters environments, the same steps can be applied, but it has to be done from the computer that created the Keyserver Cluster environment (or First Keyshard Server Instance). After loading the policy, it will get updated in the shared database and be distributed to all instances.

The command: atakama keyserver policy --dump [PATH] can be used to generate a file with the current ruleset. This can be done on both non-cluster and cluster mode, and on all instances while in cluster mode.

Quota Management

Use atakama keyserver quota list to view a list of any profiles that are currently being throttled by any rule.

You can clear profile throttling data by using atakama keyserver quota clear. For the profile(s) selected, throttling data will be reset to zero regardless of whether the profile was at quota.

A user can be given a higher quota by adding a rule set specific to that user in the policy (e.g., combining per-profile-throttle-rule and profile-id-rule).

Additional Configuration

Enabling/Disabling the Key Shard Server

All request responses can be disabled via the command:atakama keyserver disable

When the KSS is disabled, you must use the commandto re-enable it:atakama keyserver enable

To see the status of the KSS and to retrieve its ID, use command:atakama keyserver status

These commands work for both a regular Key shard server or keyshard Server instances in Cluster Mode.

Checking Key Shard Server Cluster Status:

All Key shard server instances in Cluster mode have the capacity of check the status of others instances, by using the command:

atakama keyserver instance list

The command will show both the Keyshard Server Instance ID and its status (Online/Offiline).

Failover Procedure

 Backup server setup

1. Shut down Atakama on the primary server.

2. Perform all steps defined in “Recovery Procedure” (below) on the backup server.

3. Recommended: use a KSS client to verify the functionality of the backup server.

4. Shut down Atakama on the backup server.

5. Restart Atakama on the primary server.
   

Switchover procedure

1. Confirm that Atakama is not running or connected to the Internet on the primary server.

2. Start Atakama on the backup server.

If the primary KSS dies (e.g., hard drive failure):

1. Start Atakama on the backup server, which will now take over as the primary KSS.

2. Add additional devices and recovery word sets so there are two mobile devices and two recovery word sets.

3. Repeat the steps from the “Backup Server Setup” (below) to set up a new backup server.”
   

Notes: 

1. Do not restart Atakama on the primary server until off-hours. Shut down the backup server before or as soon as possible after the primary server is started.

2. At no point should multiple instances of Atakama with the same ID (the primary and the backup) be running at the same time. This would cause client requests to fail.

• Ensure the backup server is shut down when the primary server is brought back online.

• Do not configure the backup server to launch Atakama on startup.

3. Throttling quotas are separately maintained on each server; data is not synchronized.

4. Profile changes (adding, replacing, and removing devices) should not be performed on the backup server instance.

Recovery Procedure

WARNING: Setting up a new KSS without performing recovery initializes a completely new key, requiring all existing users to re-onboard and sharing operations to be repeated.

Once the recovery procedure has been completed, end users who were previously onboarded with the KSS will continue to function uninterrupted and new end users can be onboard with the existing KSS ID.

Recovery Walkthrough:

1. Install Atakama on the new server. Do not perform onboarding.

2. Locate/download and copy the “backup key.txt” file that was created during the initial KSS  installation into the “c:\temp” on the new VM.

3. Copy the keyserver.yml policy file to %localappdata%\Atakama on the new VM. 

4. Load a profile from a device of the target profile by running the following command:
   atakama device add --method qr "My Smartphone" and scan the qr code.

5. Run the following command to load a profile from the added device:
   atakama profile recovery load-profiles --device [id]

6. To list the profiles run: atakama profile recovery list-profiles

7. Select the needed profile by running: 
   atakama profile recovery select-profile --profile [id]

8. Link the second mobile device of the target profile by running the following command:
   atakama device link --method qr [device ID] and then scan the qr code.

9. Install Atakama on a new mobile device that is not related to the current KSS profile. Tap the hamburger menu button and navigate to the "Recovery key tab". Click "Load" and enter all the security words from one of the backup keys.

10. Run the following command to link a device with loaded words:  
    atakama device add --recovery --method qr "My Smartphone 2" and scan the QR code.

11. Run the following command in order to stage the newly added device: 
    atakama profile recovery stage-new-device --device [id]

12. Run the following command to shutdown Atakama background processes: atakama --shutdown force

13. Run the following command to ingest the backup key:
    Atakama keyserver recovery-ingest-key c:\temp\backup-key.txt.kama

14. A MofNop will be sent to the device associated with the KSS profile (similar to the finalize MofNop). 

15. Approve the MofNop.

16. Run profile recovery finalize.

17. You can now add the Secure Folder(s) and launch Atakama normally.

18. Run keyserver create again to initialize the KSS by running the following command:
    On a regular Keyserver: atakama keyserver enable --backup-path %homepath%\Atakama\backup-key.txt 
    On Cluster Mode: atakama keyserver create --db-uri "mysql:host=[IP ADDRESS from the machine with MySQL],port=3306,user=[User],password=[Password assigned to that user],database=cvfs

19. Run Keyserver policy --load to load the policy file to the database and update the ruleset.