Key Shard Server


Under certain circumstances, for example automated batch processing, Atakama’s Key Shard Server (KSS) can be used instead of a phone. 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 phones.


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 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). Follow the instructions below to initialize the KSS for use in your environment.

Setup KSS Profile

Onboard Atakama on your workstation. The Atakama Profile that will be created will be used to secure the backup key for the KSS. This Atakama Profile should have at least two phones and at least five total devices (including the workstation). More devices can be added for greater redundancy.

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

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 one of the three options, onboarding the end user is automatic and proceeds without end user interaction. Once onboarding is completed, 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 config.


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. Each Secure Folder must contain at least one additional non-KSS profile because the KSS does not support granting access to other profiles.

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 which are evaluated to either true or false. Rules are the basic building blocks of policies.

Atakama provides several rule plugins that are included with the KSS (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. A user would most likely prefer to put a more permissive rule set ahead of a more restrictive one.

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, then 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

Note that 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. Note that 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.

Recovery Procedure

There can be only one active instance of a KSS with a given ID. If that instance dies, the KSS 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 the backup key .kama file that was created during initial KSS installation.

  3. Follow the steps for a regular recovery except for finalize.

    1. Any combination of linking methods and profile-loading may be used.

    2.  profile recovery status should show that you are ready to finalize.

  4. keyserver recovery-ingest-key [.kama path] will initiate a MofNop to the devices associated with the KSS profile (similar to the finalize MofNop). 

  5. Approve the MofNop.

  6. Run profile recovery finalize.

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

  8. Run keyserver enable again to initialize the KSS.

Did you find it helpful? Yes No

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