User's Guide: Account Replication

1.0 Introduction

Welcome to the Fortanix Data Security Manager (DSM) Account Replication User Guide. The Account Replication feature allows you to create and manage replicated accounts within Fortanix DSM.

The Account Replication feature is designed to help you periodically replicate data from a source account (account being replicated) on Fortanix DSM SaaS to a destination account (replication account) on your Fortanix DSM on-premises cluster. This feature ensures that your source account data is periodically backed up or transferred to the destination account for various purposes, such as disaster recovery, migration, or keeping a backup of your account to avoid losing access during downtime.

NOTE

• The source account must reside on Fortanix DSM SaaS.

• A destination account can only be configured on a Fortanix DSM on-premises cluster.

After you configure your replication account, Fortanix DSM enables you to manage the entire replication process, making it simple and reliable by automatically copying the data from your source account to the destination account periodically. This saves time and reduces the chance of errors compared to doing it manually. If the source account faces any issues or downtime, the destination account can be used as a failover system so that you do not lose access to critical data or services.

This feature is designed to help you safely back up your account data, keep two accounts in sync, and provide easy migration or failover options when needed.

1.1 How Does Account Replication Work?

When you create a new account on a DSM on-premises cluster, you can select between a regular Fortanix DSM account and a replication account. The replication account can be connected to a source account on DSM SaaS to periodically back up the data from the source account.

The replication process is controlled by a Fortanix DSM administrative app on the source account using Certificate-based authentication for a secure communication between the source and destination accounts.

The destination account generates a private key and a self-signed certificate associated with the key for secure communication. The source account uses this certificate to verify the destination account. Once authenticated, data is securely replicated, ensuring that the destination account stays synchronized with the source account.

To ensure that the source DSM SaaS can be trusted by the destination on-premises DSM cluster, the source cluster’s service certificate is used that attests that the cluster on which the source account is running is legitimate.

The replication process involves creating destination-side objects (or replicas) that correspond to source-side objects and keeping those replicas up to date with any new changes from the source account. If a scan detects that a source-side object has been deleted (or no longer accessible to the administrative (admin) app performing the scans), the corresponding replica object will also be deleted from the destination account.

2.0 Account Replication

This section outlines the requirements, replication behavior, limitations, and exceptions during replication of accounts.

2.1 Account Replication Requirements

Before setting up the destination account in Fortanix DSM, make sure to review the following requirements for successfully setting up a replication account. This will help ensure that the replication process runs smoothly, and that you are aware of any restrictions. It also details the behaviors and consequences when these criteria are not met during the replication process.

2.1.1 Source Accounts

Ensure the following requirements are met for the replication source account:

• It must reside on Fortanix DSM SaaS.

• It cannot be a reseller or child account.

• It cannot be a replication account, nor should it have been one previously.

• It cannot have any account-wide Quorum approval policies.

NOTE

If there is an issue with the source account, then the replication to the destination account will stop entirely until the issue with the source account is resolved.

2.1.2 Destination Accounts

Ensure the following requirements are met for the destination account:

• It must reside on a Fortanix DSM on-premises cluster.

• It must be a replication account created specifically for this purpose.

  NOTE

  You can convert a replication account to a regular account anytime and this action permanently ceases replication and allows the account to be fully writeable. For more information, refer to Section 6.0: Converting Replication Account to Regular Account.

• For a given source account, a destination cluster can contain at most one destination account that is currently replicating or has previously replicated that source account. You cannot create a new replication account in the destination cluster until the previous one has been deleted.

2.2 Account Data Replicated

This section lists all the source account data that will be replicated to a destination account.

• All source account objects and their attributes except the exceptions mentioned in Section 2.4: Account Replication Exceptions will be replicated to a destination account.

• All groups in a source account that satisfy the requirements mentioned in Section 3.1: Group Replication Requirements, will be replicated to a destination account. For exceptions, refer to Section 3.4: Group Replication Exceptions.

• All security objects (keys) in a source account that satisfy the requirements mentioned in Section 4.1: Security Object Replication Requirements will be replicated as replica keys to the destination account, which also contains the key material. For exceptions, refer to Section 4.4: Security Object Replication Exception.

• All cryptographic applications in a source account that satisfy the requirements mentioned in Section 5.1: App Replication Requirements will be replicated to the destination account.

2.3 Account Replication Limitations

This section outlines the limitations when replicating the data from the source account to destination account. It highlights the actions that cannot be performed in the destination account to ensure that the destination account accurately mirrors the source account.

• The destination accounts have read-only permissions, so you cannot add or modify any fields on this account. This ensures the replica matches the source account without changes.

  • You cannot create or update security objects, groups, applications, plugins, external roles, or other DSM objects in the destination account. There are some exceptions to this, refer to Section 2.4: Account Replication Exceptions.

  • You can delete existing data, but the next scan on the source account will restore the deleted objects on the destination account.

• You cannot customize the behavior of replication, such as selecting the object types, fields on object types, and so on, to replicate on the destination account.

• The source account quorum policies are not replicated to the destination account, so approval requests and quorum-based actions are not supported on the destination account.

• The destination account has restricted API functionalities. For example, operations such as key rekeying, group creation, and application (app) resets are disallowed.

2.4 Account Replication Exceptions

A replication account will attempt to create near-exact replicas of the source objects with the same semantics as the source account fields. However, there are some exceptions as listed below.

• The users from the source account are not replicated on the destination account. You must manually invite users to the destination account, and configure their permissions, roles, and so on.

• All fields related to authentication configurations can differ from the source account. This is because the users are not replicated, and the destination account may have different rules applied to its users.

• Administrative apps may differ from those in the source account.

• While the rotation policy is copied to the destination account, this account will not perform any key rotation. The key rotation operation happens only on the source account, and the destination account will detect these changes during the next scan of the source account.

• The Custom account roles and Custom group roles on the source account are not replicated on the destination account. You can create, update, and delete custom roles on the destination account.

• The destination account will have a different Account ID (acct_id) which is the account UUID and Name (name) from the source account. When creating the account, a new random UUID is generated, which cannot be changed. Additionally, the destination account name can be updated later and does not have to match the source account’s name.

• The destination account logo can be customized and may differ from the source account.

• The START DATE (created_at) displays the creation time of the destination account.

• The Total Groups, Total Apps, Total Security Objects, and so on, displayed on the DSM Home page and the Total Active Apps, Total Operations, Tokenization Operations, and so on (totals), displayed on the DSM Dashboard reflects the counts for the destination account.

• The destination account Enabled (enabled) state can differ from the source account since system administrators may want to independently control whether the destination account is enabled or not.

• The logging configuration settings such as Retention period for Audit Logs (log_retention_days), Logging invalid API requests (log_bad_requests), and Custom Log Management Integrations (logging_configs) in the destination account can differ from the source account because source-side and destination-side audit logs are different.

• The Key Expiry Alert (key_expiry_alert_config) settings are not copied to the destination account as it may contain credentials. On the destination account, this will not be set up to prevent duplicate alerts from being sent.

• The User ID (admin_id) displays the user ID of an administrator on the destination account and not the source account’s administrator’s user ID.

3.0 Group Replication

This section outlines the requirements, replication behavior, limitations, and exceptions required for the successful replication of groups in the destination account.

3.1 Group Replication Requirements

The following requirements must be met for successful replication of groups from the source account to the destination account. It also details the behaviors and consequences when these criteria are not met during the replication process.

Ensure the following requirements are met for the groups on the source account:

• It can be scanned by the version of DSM running on the destination cluster.

• It cannot be an externally backed group. For example, Cloud Data Control groups.

• It cannot have a Quorum approval policy or a Key Custodian policy.

• It cannot have Export permissions (export policy) that requires wrapped export for key material.

• It cannot be protected by a specified Key Encryption Key (KEK).

NOTE

If there is an issue with groups in the source account before replication starts, these groups and all their keys will not be replicated to the destination account. However, if such an issue occurs after the replication is complete (for example: source account gains a Quorum approval policy), the group and all its keys will be deleted from the destination account during the next scan. This action will be logged in the Fortanix DSM audit logs.

3.2 Group Data Replicated

This section lists all the data that will be replicated from the groups on the source account to the destination account.

• For each source group, the properties of the source group will be replicated to the corresponding destination group.

• All keys from the groups on the source account that satisfy the requirements mentioned in Section 4.1: Security Object Replication Requirements will be replicated as replica key to the destination account, which also contains the key material. For exceptions, refer to Section 4.4: Security Object Replication Exceptions.

NOTE

• Even if Fortanix DSM cannot populate the group in the destination account with replica keys, the destination group itself will remain in the destination account.

• Existing groups can be deleted from the destination account; however, the next scan will restore these groups, provided they meet the requirements outlined in Section 3.1: Group Replication Requirements.

3.3 Group Replication Limitations

This section outlines the limitations when replicating groups from the source account to the destination account.

If a previously replicated group in the source account gains a group Quorum approval policy, KEK, Key Custodian policy, or Export policy (Export permissions), the entire destination group, along with its keys, will be deleted from the destination account during the next scan.

3.4 Group Replication Exceptions

A group in the source account will create corresponding group in the destination account with the same properties as the source group. However, there are some exceptions, as listed below.

• The Group created by field will always be blank (Principal::System) for the group in the destination account.

• The CREATED date reflects the creation time of the destination replica, not the source group.

• The destination group’s Export permissions (export_policy) will not be set in the destination account.

• The Custom group roles in the source account group are not replicated to the group on the destination account.

4.0 Security Object Replication

This section outlines the requirements, replication behavior, limitations, and exceptions required for the successful replication of keys in the destination account.

4.1 Security Object Replication Requirements

To create replica keys in the destination account for each key on the source account, ensure that the following requirements are met for every key on the source account:

• It can be scanned by the version of DSM running on the destination cluster.

• It must be exportable.

• It must be enabled.

  NOTE

  Destroyed keys and soft-deleted keys are automatically disabled.

• It cannot be a stateful key, such as, Leighton–Micali (LMS) LMS key.

• It cannot be a virtual key.

• It cannot be protected by an export permission (export policy) that requires wrapped export for key material.

• Its Group cannot be protected by a specified KEK.

  NOTE

  • If the keys do not meet these requirements before replication starts, they will be excluded from the replication process. If a previously replicated key encounters an issue later (for example, due to the addition of key export permissions or the key loses its export permission), the corresponding replica key will remain in place, and the source key’s attributes will continue to be replicated.

  • In some cases, these replica key will be deleted instead. For more information, refer to Section 4.3: Security Object Replication Limitations.

4.2 Security Object Data Replicated

This section lists all the data that will be replicated from the keys on the source account to the destination account.

For each key in the source account:

• The replica key will contain the same key material, key ID, key permissions, key state, key size, and other attributes and tags as the source key.

• Security objects of all types including certificates and secrets are replicated provided they satisfy the requirements in Section 4.1: Security Object Replication Requirements.

• The replica key will have the same deactivation date as the source key.

NOTE

Existing replica keys can be deleted from the group in the destination account; however, the next scan will restore these keys provided they meet the requirements outlined in Section 4.1: Security Object Replication Requirements.

4.3 Security Object Replication Limitations

This section outlines the limitations when replicating keys in the source account to the destination account.

• If a key on the source cluster cannot be scanned by the version of DSM running on the destination cluster, the replication of that key will be skipped.

• If a previously replicated key in the source account becomes inaccessible or unreadable to the destination account, the corresponding replica on the destination side will be deleted.

• If a previously replicated group in the source account gains a group Quorum approval policy, KEK, Key Custodian policy, or Export policy (Export permissions), the entire destination group, along with its keys, will be deleted from the destination account during the next scan.

• Since the replica key on the destination account will not inherit key history from the source account, converting the replication account to a standard DSM account will prevent you from undoing any actions on the destination key, which is now a standard key.

4.4 Security Object Replication Exceptions

A key in the source group will create a corresponding replica key on the destination group with the same properties as the source key. However, there are some exceptions, as listed below.

• The Time (lastused_at) field for a replica key will track the last-use date and time of the destination key instead of the source key. This can be seen in the account audit logs.

• The Created by field will always be blank (Principal::System) for the replica key.

• The CREATED (created_at) date reflects the creation time of the replica key, not the source key.

• The replica key will not inherit any key history from the source key.

• The replica key will have the same rotation policy as the source key; however, the replica key will not perform any key rotation.

• Upon reaching its deactivation date, the replica key may have an enabled or disabled state that differs from the source key.

  Keys in the source account can be configured to become disabled upon deactivation using the account-wide mark_key_disable_when_deactivated field that controls this setting. However, changes to this field do not necessarily apply retroactively to existing source keys. For more information, refer to Enabling a Deactivated Key to learn about DSM version-based behavior differences.

  When a destination account replicates keys from the source account, it will fetch the latest value of mark_key_disable_when_deactivated set at the source account and apply that to the replica keys created in the destination account. This means that if a source or destination key has the deactivation date set to a future date, the source key may become disabled upon deactivation, while the destination replica does not, or vice versa. This discrepancy occurs because the source key may not automatically update to reflect the latest mark_key_disable_when_deactivated setting (as it depends on the DSM version the source account is on), unlike the destination replica key which always checks the latest mark_key_disable_when_deactivated setting at the source account.

4.5 Security Object Replication Using Fortanix DSM Clients

You can enable key export permission automatically during key creation using Fortanix DSM clients JCE, PKCS#11, CNG/EKM, and KMIP. This ensure that keys can be replicated to a destination account from a source account during disaster recovery scenarios.

• JCE: To add export permission during key creation using Fortanix DSM JCE client, refer to Clients: Java Cryptography Extension (JCE) Provider.

• PKCS#11: To add export permission during key creation using Fortanix DSM PKCS#11 client, refer to Clients: PKCS#11 Library.

• CNG/EKM: To add export permission during key creation using Fortanix DSM CNG/EKM client, refer to Clients: Microsoft CNG Key Storage Provider.

• KMIP: To add export permission during key creation using Fortanix DSM KMIP client configuration setting in the DSM UI, refer to the following documents:

  • User's Guide: Account Client Configurations

  • User's Guide: Group Client Configurations

5.0 App Replication

This section outlines the requirements, replication behavior, limitations, and exceptions required for the successful replication of certain cryptographic apps in the destination account.

5.1 App Replication Requirements

To create apps in the destination account for each key on the source account, ensure that the following requirements are met for every app on the source account:

• It must use only an API key, client certificate, or trusted CA (Certificate Authority) as the authentication methods.

• The cryptographic app’s default group on the source account must be replicable and meet the requirements outlined in Section 3.1: Group Replication Requirements for Fortanix DSM to replicate the source app. Additionally, if the default group of an already replicated app in the source account becomes problematic or no longer satisfies requirements in Section 3.1: Groups Replication Requirements, the corresponding replica app will be deleted during the next scan.

NOTE

• If the apps do not meet these requirements before replication starts, they will be excluded from the replication process. Cryptographic apps in the destination account will interact with replica keys using the source key IDs and names.

• If a previously replicated app encounters an issue later (for example, if the authentication method is updated to an unsupported one), the corresponding replica app will be deleted during the next scan.

• You cannot create new cryptographic apps in the destination account that do not meet the requirements mentioned above, although you can still create admin apps. If you wish to create new cryptographic apps beyond the ones supported for app replication, you must convert your replication account to a regular account.

5.2 App Data Replicated

This section lists all the data that will be replicated from the cryptographic apps on the source account to the destination account.

For each cryptographic app in the source account:

• The cryptographic app on the destination account will have the same app ID, app permissions, and app authentication method as the corresponding cryptographic app in the source account.

5.3 App Replication Limitations

This section outlines the limitations when replicating apps in the source account to the destination account.

• If Fortanix DSM fails to fetch the credentials for a source account app, the source app will not be replicated. If this occurs with a previously replicated app, the corresponding app in the destination account will be deleted during next scan.

  NOTE

  Existing apps can be deleted from the group in the destination account; however, the next scan will restore these apps, provided they meet the requirements outlined in Section 5.1: App Replication Requirements.

• If the authentication method of an already replicated app in the source account is updated to a value not listed in Section 5.1: App Replication Requirements, the corresponding replica app will be deleted during the next scan.

5.4 App Replication Exceptions

A cryptographic app in the source group will create a corresponding app on the destination group with the same properties as the source app. However, there are some exceptions as listed below.

• The Type (last_operations) field for a destination app will track the usage of the destination app instead of the source app. This can be seen in the account audit logs.

• The Time (lastused_at) field for a destination app will track the last-use date and time of the destination app instead of the source app. This can be seen in the account audit logs.

• The Created by field will always be blank (Principal::System) for the replica app.

• The CREATED (created_at) date reflects the creation time of the replica app, not the source app.

• The destination app may have fewer group memberships than the corresponding source app as some source groups might not satisfy the account replication requirements as described in Section 2.1: Account Replication Requirements. In this case not all groups the source app belongs to may be replicated to the destination account.

• The names or IDs of groups and DSM objects may differ between the source and destination systems. The system handles these differences automatically, but it is important to know that the destination group might have different names or IDs from the source group account.

6.0 Converting a Replication Account to a Regular Account

During events such as disaster recovery, you can convert a destination account into a regular account, making it fully writeable and permanently ceasing replication from the source account. After conversion, you can make changes to the account as you would with any other regular DSM account, such as adding new security objects, groups, and other configurations.

NOTE

This action is irreversible. If replication of the source account is required again, then you must delete the current account (which was previously a destination account) and create a new destination account on the destination cluster.

7.0 Set Up Account Replication

Fortanix DSM allows you to configure a destination account for a source account to replicate data, safeguarding against data loss and enabling disaster recovery in case of system failure or other disruptions. This section outlines the procedure for configuring a replication account for a new DSM source account an existing one.

7.1 Prerequisites

• Before you begin, ensure that you have an active Fortanix DSM source account set up to configure account replication. For more information on the steps to create a new source account, refer to User's Guide: Getting Started with Fortanix Data Security Manager – UI.

• After creating the source account, copy the URL of the source cluster to use during the replication account creation process, as described in Section 7.2: Creating Replication Account. For example, https://amer.smartkey.io/.

7.2 Creating a Replication Account

Perform the following steps to create a replication account:

1. Log in to the Fortanix DSM destination cluster and go to the “My Accounts” page.

2. In the My Accounts section, click CREATE NEW REPLICATION ACCOUNT.

3. On the Let’s configure disaster recovery for account page, do the following:

   1. Enter the Account name of the destination account.

   2. Enter the source cluster URL as copied earlier in Section 7.1: Prerequisites.

   3. Click the GET CERTIFICATE button for the destination cluster to generate a private key and a self-signed certificate associated with the key for secure communication between the source and destination accounts. The certificate will be downloaded on the system.

      NOTE

      This certificate does not have an expiration date.

4. Navigate away from the destination account user interface (UI) to the source account UI to upload the certificate downloaded in the previous step. Perform Steps 1-4 in Section 7.3: Create Admin App on the Source Account and copy the admin app UUID.

5. Enter the copied app UUID in the Admin app UUID field and click NEXT.

   

6. On the Replication frequency page, enter the desired number of hours for the replication interval which is the time gap between two consecutive account replication scans.

7. Click FINISH.

   

   Wait a few minutes for DSM to establish synchronization between the source and destination accounts for replication. A success message will appear in the top-right corner of the page.

You will then be able to see that the account you are viewing is a replication account.

7.3 Create an Admin App on the Source Account

Perform the following steps to create an administrative app on the source account:

1. On the source account UI, click the Settings → ADMINISTRATIVE APPS menu item.

2. Click the ADD ADMINISTRATIVE APP button to add a new administrative app that is used to communicate between the source and destination accounts.

3. On the New Administrative App page, do the following:

   1. Enter the required app name.

   2. Select the Certificate option as the Authentication method.

   3. Click UPLOAD CERTIFICATE, browse and upload the saved certificate as saved in Step 3 (c) in Section 7.2: Creating a Replication Account.

   4. Click CREATE.

   

4. In the detailed view of the newly created admin app, copy the UUID to use in the destination account to establish the connection between the source and destination accounts.

   

8.0 Behavior of Scans

In the destination account, scans are periodic operations that run in the background to replicate accurate data from the source account to the destination account. They download key materials from the DSM source account, and help verify that everything is synchronized correctly and ensure a smooth replication process.

Scans are scheduled to run periodically, and frequency of scans is determined by the configuration settings in the destination account UI. If data is deleted from the destination account, it will be restored during the next scan from the source account.

Users will be able to obtain the following information about a summary of recent account replication scans performed:

• Any in-progress scans – This is displayed with a status indicator to show if a scan is in progress or, if no scan is running, or when the next scan will start.

• The last completed scan – Displays the most recent scan that ran to completion.

• The last successful scan – Displays whether the last completed scan was successful.

Each scan performed, whether successful or not, will be audit logged in the DSM audit logs on the destination account. These logs will help you troubleshoot and fix any ongoing issues.

9.0 Troubleshooting

This section lists issues along with possible workarounds that you might encounter during the account replication process.

{
  "purpose": {
    "$type": "AccountReplication",
    "connection_settings": {
      "url": "<DSM SaaS URL>",
      "active_replication_credential": "<credential-id>"
    },
    "scan_settings": {
      "auto_scan": {
        "scan_interval_hours": <desired frequency>
      }
    }
  }
}