Domain Management

A domain is a logical division that isolates users and cryptographic keys. Resources like keys are isolated to a single domain and cannot be accessed across domains.

CipherTrust Manager's domains form its multitenancy model. Multitenancy enables the creation of multiple restricted or local domains within a single CipherTrust Manager appliance. Enterprises can use multitenancy to segregate key access (or other resource access) to better control usage of product by line of business or use case.

Every CipherTrust Manager appliance has a root domain by default. Additional child domains can be created, and child domains can have their own children domains. We have validated 100 domains for Virtual CipherTrust Manager k170v, and 1000 domains for every other model. A domain administrator role controls the creation, deletion, update, and user assignment of domains.

You can optionally anchor a child domain to a Luna Network HSM partition during creation. All keys and secrets within an HSM-anchored domain are wrapped and unwrapped by the HSM itself. This strengthens the security and isolation of the multitenancy model. There are back up and performance considerations for this option, which should be planned for before enabling the feature.

Not all resources are segregated. Certain settings and configurations are only configurable in the root domain. This includes:

• System settings such as NTP servers.

• Authentication settings such as LDAP servers.

CipherTrust Manager allows you to partition a single instance into multiple domains, and allows separate administrators with separation of duties to manage encryption keys, security controls, and auditing in each domain.

Domain Planning

As part of configuring CipherTrust Manager, the domain administrator should think about the requirements for the domains to be included within the configuration.

Among the requirements to be considered before creating the domain are the following:

• Administration

  • Number and type of administrators required. Administrators can assign user groups to the domain and manage child domains. If administrators have the correct permissions, they can also perform operations on domain resources directly.

  • Number of users requiring access to the domain's resources.

• Administrative operations/practices

  • Backup and Key Rotation Schedule

  • Access to and storage of audit records and activity logs on an external log forwarder for audit purposes. By default, audit records and activity logs from a child domain are redirected to the log forwarder configured for the parent domain. The redirection setting is described below.

• Selecting Parent CA

  • The default CA of a domain is signed by the parent CA selected while creating the domain.

  • The duration of domain's default CA cannot be more than the parent CA duration.

  • The maximum duration of a domain's default CA can be 10 years.

• Key hierarchy

  If you choose to anchor the domain to an HSM, there are additional dependencies and limitations:

  • Configuration of the HSM partition(s) is required. HSM-anchored domains are only support with NTLS partitions, not with STC partitions.

  • Configuration of the HSM connection(s) is required.

  • To successfully backup and restore HSM-anchored domain contents, the CipherTrust Manager needs an active connection to the HSM partition. As well, the destination domain must be created with a connection to the same HSM partition; an HSM connection cannot be added after creation.

  • There might be a performance impact to applications that frequently interact with the domain data keys for cryptographic operations and key exports. The key caching system property can improve performance for such applications. This system property caches data key material in CipherTrust Manager memory, so that subsequent requests to use a data key don't require the HSM to unwrap the key.

    Note

    Consult documentation for CipherTrust connectors to see if data key caching would be beneficial to performance in your deployment. The CipherTrust Manager key cache might not noticeably improve performance for connectors which also cache keys client-side.

User Management

When a domain is created, one or more initial administrators must be defined. When administrators subsequently log into the domain, they can use assign additional users to the domain and also use groups to assign user permissions.

The defined Admins should, at minimum, have group permissions to create domains, users, and groups. You can assign the admins to the 'Domain Admins' and 'User Admins' system-defined groups to have the correct permissions.

Creating Domains

A new domain is automatically a child domain of the logged-in domain at the time of creation. So, if you are logged into the root domain, and create a new domain, the new domain is a child of root.

By default, a parent domain and its descendants are part of the same certificate chain. You can create domains in a parent-child hierarchy down to ten levels before having to manually replace their associated certificates for client certificate authentication.

The workflow to create a domain varies depending on whether you wish to have the domain anchored in CipherTrust Manager software or in an HSM partition.

To create a domain anchored in CipherTrust Manager software

1. Review the domain planning considerations.

2. Log into the CipherTrust Manager Management Console as an Admin with domain creation permissions.

3. Navigate to Admin Settings > Domains.

4. Select Add Domain.

5. Enter the following information in the Add Domain dialog:

   • Name: Name of the domain

   • Admins: Define the initial set of Admins who can log into the domain, assign users to groups to the domain, and create child domains. These Admins should have the correct permissions.

   The following information is optional:

   • Parent CA: Each domain has a default Certificate Authority (CA) automatically created. This field defines the parent CA which signs the Default CA for the new domain. If no parent CA is provided, the oldest CA in the root domain is used.

   • Allow Subdomain User Management: Select the check box to allow the creation and management of users in non-root domains.

   • Meta: Additional reference information regarding the domain. Must be JSON formatted. This can be used to attach information – such as the department or contact details – to the domain. It can then be queried and viewed later. This field is not used internally by CipherTrust Manager.

To create an HSM-anchored Domain

1. Review the domain planning considerations, especially the key hierarchy considerations.

2. Configure a Luna Network HSM version partition following Luna Network documentation.

   Supported Luna Network HSM firmware versions are 7.4.x and higher. Consult Luna Network HSM documentation for FIPS 140-2 certified versions.

3. As an Admin with Connection Manager permissions, configure a connection to the HSM partition in Connection Manager.

   Warning

   Thales strongly discourages using a Luna HSM partition containing the CipherTrust Manager root of trust keys for HSM-anchored domains. Do not add a connection to a Luna HSM root-of-trust partition with Connection Manager.

4. As an Admin with domain creation permissions, navigate to Admin Settings > Domains.

5. Select Add Domain.

6. Enter the following information in the Add Domain dialog:

   • Name: Name of the domain

   • Admins: Define the initial set of Admins who can log into the domain, assign users to groups to the domain, and create child domains. These Admins should have the correct permissions.

   • HSM-anchored domain: Select the check box to anchor the domain to an HSM.

   • HSM connection: Use the drop-down to select the partition connection you created in step 3.

   The following information is optional:

   • Parent CA: Each domain has a default Certificate Authority (CA) automatically created. This field defines the parent CA which signs the Default CA for the new domain. If no parent CA is provided, the oldest CA in the root domain is used.

   • HSM KEK label: A name for the HSM Key Encryption Key (KEK) stored in the HSM partition. If not provided, a random UUID is assigned for KEK label. You can rotate the initial HSM KEK after creation.

   • Meta: Additional reference information regarding the domain. Must be JSON formatted. This can be used to attach information – such as the department or contact details – to the domain. It can then be queried and viewed later. This field is not used internally by CipherTrust Manager.

Deleting Domains

For HSM-anchored domains, the HSM KEK remains in the HSM partition. If desired, you can clean up this key by interfacing to the HSM partition directly, outside of CipherTrust Manager.

To delete a domain:

1. Log into the CipherTrust Manager Management Console as an Admin with domain creation permissions.

2. Navigate to Admin Settings > Domains.

3. Click the overflow icon () corresponding to the desired domain and click Delete.

   A confirmation pop-up appears.

4. Read the confirmation text and type the name of the domain to confirm.

5. Click Delete to finalize your action.

Certificate-based Login for Domain Users

Add New Domain

1. Deploy the CipherTrust Manager.

2. Log on to the CipherTrust Manager Management Console as an administrator with domain creation permissions.

3. In the left pane, click Admin Settings > Domains.

4. Select Add Domain.

5. Enter the required details. Refer to the To create a domain anchored in CipherTrust Manager software section for the description of fields.

6. Select Allow Subdomain User Management.

7. Click Save.

Add New Domain User

1. Switch to the newly created domain.

2. Navigate to Access Management > Users.

3. Click Add User and enter the required details.

4. Select Allow user to login using certificate. Refer to Enable the "Certificate based Login" Option for a User for details.

5. Click Add User to save the details.

Download Local CA Certificate

1. Navigate to CA > Local.

2. Click Add Local CA.

3. Specify the required details. Refer to Create and Download the Web Certificate for details.

4. Under Name, click the link of the newly generated local CA.

5. Click Issue Certificate.

   1. Enter the Common Name for this certificate.

      Note

      This common name should be the same common name that you specified while creating the user.

   2. Select the desired algorithm (RSA or ECDSA).

   3. In the Name field, specify the same details that you specified in the certificate_subject_dn property of the user.

   4. Click Issue Certificate.

   5. Click save private key to download the key.pem file.

   6. Click Issue Certificate. The newly created certificate is displayed in the certificates list.

   7. Download the certificate issued by the local CA and save it at the same location where the private key is saved.

Download External CA and Update Certificate

1. Navigate to CA > External.

2. Download the external CA.

3. Append the local CA and external CA to the certificate downloaded above.

Create and Import PKCS#12 (PFX) File

1. Run openssl pkcs12 -export -out user.pfx -inkey key.pem -in certificate.pem. Refer to Create and Install pkcs12 Formatted Certificate for details.

2. Import user.pfx to truststore.

Log on as Domain User

1. Clear the browser cookies.

2. Select the web certificate and log on to the CipherTrust Manager as domain user.

Domain Authentication

Once the domain(s) have been created, the specified Administrator can log in to the domain. Users that are assigned to the domain can also login to the domain to perform key operations.

GUI

In the GUI, in the upper right hand corner, click the Root/Admin link and select Switch Domains. You are now taken to the specified domain. From this point forward, all key management and admin activity is constrained to the selected domain.

CLI

In the CLI, you operate in the root domain by default. There are two ways to perform actions inside a child domain:

• Log into the domain with the ksctl login --user <user_with_domain_permission> [--password <user_password>] --domain <domain_name_or_id> command. If you don't specify the password, you are prompted for it. All subsequent commands in the session are within the domain.

• Use the --domain <domain_name_or_id> option with --user <user_with_domain_permission> for the particular key management or administrative command you wish to perform. You can specify the password with --password or enter it when prompted

REST API

In the REST API, the POST command to authenticate goes to the root domain by default. You can include a child domain name in the schema with domain, as well as the domain administrator username and password. After this initial authentication, subsequent API requests apply to the authenticated domain.

You can also use the GET /v1/auth/self/domains/ endpoint to return a list of domains that the current user is assigned to.

Domain Scoped Backups

You can scope a backup to a single domain.

Rotating the HSM KEK

You can rotate the HSM KEK for HSM-anchored domains, which re-wraps all the keys and secrets in the domain with a different key held in an HSM partition. This is a different option than editing the HSM KEK label, which just restores the association between a domain and its active HSM KEK.

The following rotation operations are available:

• Rotate the HSM KEK

• Check the status of a KEK rotation

• Retry a failed rotation

Rotate the HSM KEK

1. Log into the CipherTrust Manager Management Console as an Admin with domain permissions.

2. Navigate to Admin Settings > Domains.

3. Click the overflow icon () corresponding to the desired domain and click View/Edit.

   On the details page, the KEK list is visible, with the current KEK at the top of the list, and all previous KEK listed below.

4. Click the Rotate KEK button.

5. Change the default rotation settings, if desired. By default, a new HSM KEK is created with a randomly generated UUID label, and stored in the existing HSM partition.

   1. To store the HSM KEK in a different HSM partition, select a different HSM Connection.

   2. To rotate to an existing KEK, enter its label as the HSM KEK Label.

   3. To create a new KEK with a unique custom label, enter the label as the HSM KEK Label.

      Note

      If there is an existing KEK present in the partition with the label you enter, CipherTrust Manager rotates to that existing KEK.

6. Click Rotate KEK to confirm.

Check the Status of a KEK Rotation

While a KEK rotation is ongoing, a notice above the KEK List shows progress for re-wrapping all the keys present on the domain, and the status of the KEK is reported as Started in the KEK List.

If a rotation times out or otherwise fails, the partially rotated KEK displays a Failed status in the KEK List. Click on the row to view details of the failed rotation job, including start and finish times, and Meta details of total domain keys, number of domain keys rotated, and number of domain keys that failed to be rotated.

Past successful rotations display a Success status. Click on the row to view details of a successful rotation job, including start and finish times, and Meta details of total domain keys and number of domain keys rotated.

Retry a Failed Rotation

If an HSM KEK rotation times out or otherwise fails, you can retry the rotation.

1. Log into the CipherTrust Manager Management Console as an Admin with domain permissions.

2. Navigate to Admin Settings > Domains.

3. Click the overflow icon () corresponding to the desired domain and click View/Edit.

   On the details page, the KEK list is visible, with the current KEK at the top of the list, and all previous KEK listed below.

4. In the KEK list, find and the desired HSM KEK with Failed status. Click the Retry button at the far right of the row.

   A confirmation dialog pops up.

5. Click Retry KEK Rotation to confirm.

   The rotation continues from its previous point. Keys that that were successfully re-wrapped in previous failed rotation attempts are not wrapped again.

Editing HSM-anchored Domains to Recover Lost HSM KEK

You can edit HSM-anchored domains to recover a lost association to the active HSM KEK stored in an HSM partition. This is helpful if CipherTrust Manager's connection to the HSM partition was deleted, if the HSM KEK was moved to a different HSM partition, or if the HSM KEK's label was changed directly on the HSM.

To re-associate a domain with its original HSM KEK:

1. Log into the CipherTrust Manager Management Console as an Admin with domain permissions.

2. Navigate to Admin Settings > Domains.

3. Click the overflow icon () corresponding to the desired domain and click View/Edit.

4. Under the HSM Domain Connection section, select another HSM connection from the dropdown if desired.

5. Edit the HSM KEK Label, if desired. A key with this label must already exist on the HSM partition.

   This operation does not re-wrap domain keys and secrets. Rotate the HSM Kek to re-wrap those objects.

6. Click Update to finalize your changes.

Log Forwarder Redirection

Log forwarder redirection is a setting to send audit records, KMIP activity logs, and NAE activity logs from a child domain to the log forwarder configured for a higher-level domain.

When an audit record, NAE activity log, or KMIP activity log is created in a child domain with log forwarder redirection, CipherTrust Manager checks the domain's immediate parent for a configured log forwarder. If the immediate parent also has log redirection enabled, CipherTrust Manager also checks its parent, the child domain's grandparent, for a configured log forwarder. CipherTrust Manager continues checking for log forwarders further up the domain hierarchy every time it finds the log redirection setting. Every time CipherTrust Manager finds a configured log forwarder in a domain, it forwards log messages to that log forwarder.

Users in the Domain Admins or Application Administrators group, such as admin can enable or disable log forwarder redirection. When a new child domain is created, log forwarder redirection is enabled by default. Existing child domains which were created in a version lower than 2.16.0 have log forwarder redirection disabled after upgrade.

Enabling or disabling log forwarder redirection in web console UI:

1. Login to the child domain as a user in the Domain Admins or Application Administrators group, such as admin.

2. Navigate to Admin Settings > Logs.

3. Click the Log Forwarders tab.

4. Click the Redirect Log Forwarder toggle to enable or disable log forwarder redirection.

Enabling or disabling log forwarder redirection in ksctl CLI:

Login to the child domain as a user in the Domain Admins or Application Administrators group, such as admin. For example:

ksctl login --user <user_with_domain_admin_permission> --password <user_password> --domain <domain_name_or_id>

• The following command disables log forwarder redirection.

  ksctl domains log-forwarders-redirection disable
  

• The following command enables log forwarder redirection.

  ksctl domains log-forwarders-redirection enable
  

• The following command displays log forwarder redirection status

  ksctl domains log-forwarders-redirection status
  

Managing Syslog Messages Redirection to Parent Domain (Legacy Syslog) using ksctl

Syslog messages redirection allows you to send the legacy syslog messages of the current domain to the legacy syslog server configured in its parent domain.

If the current domain is receiving the syslog messages from its child domain, those syslog messages will also be sent to the legacy syslog server configured in the parent domain of the current domain.

It allows you to perform the following operations:

• Enabling/Disabling syslog messages redirection

• Status of the syslog messages redirection

Enabling/Disabling Syslog Messages Redirection

To enable syslog messages redirection to the parent of the current domain, run:

ksctl domains syslog-redirection enable

To disable syslog messages redirection to the parent of the current domain, run:

ksctl domains syslog-redirection disable

Getting Status of Syslog Messages Redirection

It returns the syslog messages redirection status of the current domain. This status shows whether the redirection to parent domain is enabled or disabled. To get the status, run:

ksctl domains syslog-redirection status