Atakama Key Shard Server


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 


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

Run the following command in cmd or Powershell:

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

(ex: 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. 

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.

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


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


Basic rule for applying per-profile limits on approvals.


Basic rule for exact match of profile ids.


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 --reload

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.

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

Disabling the Key Shard Server

All request responses can be disabled via atakama keyserver disable.

When the KSS is disabled, you must use the atakama keyserver enablecommand (with its typical args) to re-enable it.

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

Failover Procedure

In order to enable rapid switchover in the event that the primary KSS fails, you will need to preload the backup key onto a second server instance. Once this is complete, you need only to start the Atakama application on the backup server at the time of switchover. 


 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

If the primary KSS is temporarily offline (e.g., unplanned Windows update):

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


  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.

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

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

Recovery Procedure

There can be only one active instance of a KSS with a given ID. If that instance dies and there is no backup server, the one KSS instance must be recovered.

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 .kama” file that was created during 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 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. Load one set of recovery words to a completely new mobile device.

  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 ingest the backup key:
    Atakama keyserver recovery-ingest-key c:\temp\backup-key.txt.kama

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

  14. Approve the MofNop.

  15. Run profile recovery finalize.

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

  17. Run keyserver enable again to initialize the KSS by running the following command:
    atakama keyserver enable --backup-path %homepath%\Atakama\backup-key.txt

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.