Business Processes KMS Tenant

This chapter describes the processes and tasks that the KMS Tenant operator performs using the KMS-UI application with "KMS Tenant".

"KMS Tenant" provides methods for the following tasks:

  • Manage or add KEK (or protected KEK)

  • Manage or add KMS clients

  • Manage or add application namespaces

  • View CAs (certification authorities)

  • Manage or add tenant users

  • Manage own account (Keycloak etc.)

The necessary identification and authentication to the KMS Tenant application is described in the following process steps:

Table 1. Process steps: Login to KMS Tenant
Process steps

01

Call the URL of the KMS-UI application with the browser, e.g.

<ipaddress>:<port>/kms-ui/

select the "Sign in" button and sign in using the username and password provided by an admin or tenant (e.g., in a sealed envelope or encrypted email). For example, one possible login strategy is Keycloak.

02

After a successful login, the start page ("Dashboard") is displayed. The page features various buttons and a navigation menu (sidebar), which is typical for most pages of the KMS-UI web application and the KMS Tenant.

03

It is recommended to change the randomly assigned username and initial password to a meaningful name and a new password during the initial login.

Furthermore, the personal information (e-mail, last name, first name) should be completed.

To do this, proceed as follows (when using Keycloak):

  1. Select "Profile" in the navigation menu;

  2. In the configuration interface of your authentication method (e.g. Keycloak), select "Personal information";

  3. Change your username and verify that "Email", "First Name", "Last Name", and "Language" are correct.

  4. Click on "Save".

  5. In the configuration interface of your authentication method (e.g. Keycloak), select "Account Security" → "Login";

  6. Update your password .

  7. Return to "KMS Tenant" via the URL of the KMS-UI application and log in again (see step 01).

04

From any page (see step 02), the desired functionality can be selected at any time. The following steps must be performed:

  • Open the sidebar to get to the navigation menu;

  • Select the appropriate menu item in the navigation menu;

  • Select the corresponding submenu item in the drop-down menu.

The functionalities offered in the sidebar depend on the selected submenu item. Some functionalities can also be selected directly by selecting the corresponding buttons.

From any page, it is also possible to go back to the dashboard by clicking the "Dashboard" button, clicking on the MTG logo, or clicking on the "KMS Tenant" button.

05

Other functionalities:

  • Configure authentication method

  • Switch application

  • Log off from the "KMS Tenant" application

To use these functionalities, proceed as follows:

  1. On any page, open the drop-down menu in the upper right corner of the KMS-UI web application by clicking on the "User" icon;

  2. Use the drop-down menu:

    • Click "Profile" to go to your authentication method settings (e.g. Keycloak);

    • Select "Applications" to switch to a different available ERS applications, if any are installed;

    • Click "Logout" to log out of the "KMS Tenant" application.

Alternatively, you can access the "Profile" and "Logout" functionalities from the navigation menu in the sidebar.

06

Change language:

To change the language of the KMS-UI web application, please select the drop-down menu in the bottom right of the footer on any page of the web application. Here you can switch between "en" for English and "de" for German.

07

Search, sort and export in list views:

All objects that are managed with the KMS-UI web application are displayed as lists in their corresponding "Show" view. The structure of these lists is very similar and is usually characterized by the following features:

  • There is a search bar to search for objects by name;

    • In addition to the search bar, there is the possibility of an advanced search with fine-granular filters;

    • A non-specified ("empty") search means that all corresponding objects are displayed;

  • Using the boxes, individual objects can be selected as targets for the actions (access to them through the "Actions" button);

    • The selected objects can be exported as a CSV file using the "Actions" button;

  • The individual list elements can be sorted by the corresponding column by clicking on the table header;

  • The user pagination, search filtering and visible columns choices for each table are saved.

  • The button next to "Actions" can be used to change the columns to be displayed;

  • For individual objects, a detailed view can be opened by clicking on "Details".

P-KMS-TNT-01 - KMS-Tenant User (create, modify, delete)

Table 2. Profile: KMS-Tenant User (create, modify, delete)
profile

Name

KMS-Tenant user (create, modify, delete)

Purpose

Only tenant operators are allowed to use the KMS Tenant application, which provides methods for managing and configuring the tenant’s workspace, e.g. managing tenant users, KMS clients, (protected) KEKs and application namespaces.

With the creation and setup of a tenant on the KMS platform, at least 2 tenant user accounts have already been created. The access data has been transferred to the persons responsible for the tenant’s area. This gives the tenant access to the "KMS Tenant" application described here and thus the ability to perform tenant-specific (client-specific) tasks (tenant self-administration).

The description of the administration of tenant users is the subject of P-KMS-TNT-01. This includes in particular the administration of the accounts of tenant users as well as the creation of additional tenant users.

Responsibility

KMS-Tenant (Operator)

Working tool(s)

Browser, KMS-UI web application

Precondition/
Input

The KMS platform is up and running.

The KMS tenant user is logged into the KMS-UI application with their tenant user account.

Postcondition/
Output

  • A new KMS Tenant user has been created, or

  • the own KMS Tenant user has been changed, or

  • an existing KMS Tenant user has been deleted.

Remarks

After creating a new tenant user account, the initial password should be securely sent to the appropriate person (e.g., via encrypted email).

The current user should not be able to use and reset this initial password without the new user noticing (e.g., to prevent misuse of the new account by the approving user). Therefore, the first time a tenant user logs in with a newly created tenant user account, the tenant user will be prompted to change their initial password.
Table 3. Process steps: Tenant User (create, change, delete)
Process steps

01

Display the list of tenant users:

  1. In the navigation menu (in the sidebar), select "Tenant Users" → "Show" (in the drop-down menu).

02

Create a tenant user:

  1. Click "Create new Tenant User" above the tenant users list (see step 01) (alternatively: "Create …​" → "Tenant User" or "Create" in the "Tenant User" drop-down menu in the sidebar);

  2. The password will be generated and offered in a form. To make the password visible, the corresponding field must be clicked. The password can also be saved to the clipboard by clicking on the "Copy" button.

    By clicking "Copy all data" all access data will be copied and saved to the clipboard as follows:

    {
   "component":"KMS-Tenant",
   "username":"...",
   "password": "..."
}

    The process is completed with the creation of the account and the corresponding password. The generated access data must be securely transferred to the responsible person. This is an organizational process that must be reliably regulated between the parties involved.

03

Change own tenant user:

  1. In the list of tenant users (see step 01), select "Details" on the tenant user they are currently logged in with;

  2. Select "Edit" ;

  3. Edit "First Name," "Last Name," or "Email";

  4. Click "Save".

This is only possible for your own tenant user.

04

Delete tenant user:

  1. In the list of tenant users (see step 01), select "Details" on the tenant user you want to delete;

  2. Review the information displayed and click "Delete";

  3. Confirm the action.

When deleting a tenant user, at least two (active) tenant users must remain. You cannot delete the currently logged in tenant user.

P-KMS-TNT-02 - KEKs (create, activate, delete)

Table 4. Profile: KEKs (create, activate, delete)
Profile

Designation

P-KMS-TNT-02 - KEKs (create, activate, delete)

Purpose

For security reasons, a tenant’s key material must not be stored unencrypted in the KMS database. For this purpose, each tenant uses a so-called KEK (Key-Encryption-Key), which serves as the master key for the encryption of its own key material.

The tenant itself is responsible for the creation and administration of the KEK.

The description of the management of KEKs is the subject of P-KMS-TNT-02.

Responsibility

KMS-Tenant (Operator)

Working tool(s)

Browser, KMS-UI web application

Precondition/
Input

The KMS platform is up and running.

The KMS tenant user is logged into the KMS-UI application with their tenant user account.

Tenant and HSMs are set up.

At least 1 HSM profile has been created for the tenant by the KMS admin.

Postcondition/
Output

  • A new KEK has been created for a tenant, or

  • an existing KEK object was changed, or

  • an existing KEK object was deleted.

Remarks

Because the KEK is stored in the secure environment of an HSM, the KMS tenant operator can only access a KEK using the "key management" credentials stored in a tenant’s HSM profile (see the HSM Profiles chapter). This requires a duplicate control sequence that requires the HSM user "Key Management" credentials to be restored via the election system.

It should be noted that each tenant can create multiple KEKs, but only one KEK is active at a time. Only the active KEK is used to encrypt the key material.

The KMS does not re-encrypt existing objects when a new KEK is created, as this would be very time-consuming. Only new objects added to the KMS are encrypted with the new KEK.
Table 5. Process steps: KEKs (create, activate, delete)
Process steps

01

Display the list of KEKs:

  1. In the navigation menu (in the sidebar), select "KEKs" → "Show" (in the drop-down menu). The list shows KEKs and protected KEKs.

02

Create KEK:

  1. Click on "Create KEK" above the list of KEKs (see step 01) (alternatively: "Create …​" → "KEK" or "Create KEK" in the "KEKs" drop-down menu in the sidebar);

  2. Enter a name for the KEK;

  3. Click "Select" and select the desired HSM profile from the list;

  4. Click on "Apply" to create a KEK.

The new KEK is disabled by default, unless it is the first KEK for this tenant.

03

Activate/deactivate a KEK:

  1. Click on the "Details" button for the corresponding KEK in the list of KEKs (see step 01);

  2. Click on "Activate"/"Deactivate" and confirm the action.

Normally, exactly one KEK should be active for one tenant. When the first KEK is created, it is automatically activated. If multiple KEKs are configured, activating one KEK will deactivate the current active KEK.

04

Delete a KEK:

  1. Click on the corresponding "Details" in the list of KEKs (see step 01);

  2. Click on "Delete" and confirm the action;

If the operation was successful, the KEK has been deleted.

Only disabled (inactive) KEKs can be deleted (see step 03).

P-KMS-TNT-03 - Protected KEKs (create, activate, add HSM profile, remove HSM profile, delete, restore)

Table 6. Profile: Protected KEKs (create, activate, add HSM profile, remove HSM profile, delete, restore)
Profile

Designation

P-KMS-TNT-03 - Protected KEKs (create, activate, add HSM profile, remove HSM profile, delete, restore)

Purpose

Using conventional HSM KEKs for any cryptographic operation is simple and secure, but not the best solution in all cases.

The KMS provides an alternative to traditional KEKs, the so-called "KEK protection mode".

In this mode, the actual encryption/decryption is done in memory (using software KEKs), while the HSM is used only for initial derivation and occasional renewal of said KEKs.

This has the following advantages:

  • Since the HSM is not required for every operation, most of the processing can be offloaded to the application server, which is often much cheaper to scale both horizontally and vertically.

  • Since the chosen key derivation method does not require symmetric encryption, this mode can also be used with HSMs that only support asymmetric cryptography.

  • It is possible to configure more than one HSM/HSM profile to protect the same software kek, reducing the risk of hardware malfunction. This is of great importance for HSMs that do not support backup functionality.

Responsibility

KMS-Tenant (Operator)

Working tool(s)

Browser, KMS-UI web application

Precondition/
Input

The KMS platform is up and running.

The KMS tenant user is logged into the KMS-UI application with their tenant user account.

Tenant and HSMs are set up.

At least 1 HSM profile has been created for the tenant by the KMS admin.

Postcondition/
Output

  • A protected KEK has been created for a tenant, or

  • an existing KEK object was changed, or

  • an existing KEK object was deleted.

Notes

While the protected KEK itself is stored in-memory, the key pair needed to derive it is stored in an HSM, which means that the KMS tenant operator can only access a KEK by using the "Key Management" credentials stored in a tenant’s HSM profile (see chapter HSM Profiles). This requires a duplicate control sequence that requires the HSM user "Key Management" credentials to be restored via the reconciliation system.
Table 7. Process steps: Protected KEKs (create, activate, add HSM profile, remove HSM profile, delete, restore).
Process steps

01

Display the list of (protected) KEKs:

  1. In the navigation menu (in the sidebar), select "KEKs" → "Show" (in the drop-down menu). The list shows KEKs and protected KEKs.

02

Create protected KEK:

  1. Click on "Create …​" → "KEK" at the top right of the web application or "Create KEK (protected)" in the "KEKs" drop-down menu in the sidebar;

  2. Enter a name for the protected KEK;

  3. Click "Select" and select the desired HSM profile from the list;

  4. Click on "Apply" to create a protected KEK;

  5. A backup string will be displayed. Be sure to save this backup securely before leaving the page, as it will not be displayed a second time. Click the button to copy the backup string to the clipboard.

You can later use this backup string to restore the KEK to the initially configured HSM/HSM profile in the event of a major failure (see Step 08).

The new protected KEK is disabled by default unless it is the first KEK for that tenant.

03

Activate/Deactivate a protected KEK:

  1. Click the "Details" button for the corresponding protected KEK in the list of KEKs (see step 01);

  2. Click "Activate"/"Deactivate" and confirm the action.

Normally, exactly one KEK should be active for one tenant. When the first KEK is created, it is automatically activated. If multiple KEKs are configured, activating one KEK will deactivate the current active KEK.

04

Adding an HSM profile to a protected KEK:

  1. Click on the corresponding "Details" in the list of KEKs (see step 01);

  2. View the "HSM Profiles" section;

  3. Click on "Add HSM Profile" to add an HSM profile to protect this KEK;

  4. Click "Select" and select the desired HSM profile from the list (Note: You cannot use the same HSM profile twice for the same protected KEK);

  5. Click "Add".

05

Removing an HSM profile from a protected KEK:

  1. Click the "Details" button for the corresponding protected KEK in the list of KEKs (see step 01);

  2. View the "HSM Profiles" section;

  3. Click "Remove" on a configured HSM profile to remove it.

Only when all HSM profiles are removed, you can delete the protected KEK (see step 07) or restore the HSM profiles configured at creation (see step 06).

06

Restore HSM profiles of a protected KEK from a backup string:

  1. Click the "Details" button for the corresponding protected KEK in the list of KEKs (see step 01);

  2. Enter the backup string generated during creation (see step 03) in the "Backup String" input field;

  3. Click on "Select" and select the desired HSM profile from the list;

  4. Click on "Create from backup".

You can restore the configuration of a protected KEK only if there are currently no HSM profiles protecting it. To remove HSM profiles, see step 05.

07

Deleting a protected KEK:

  1. Click the "Details" button for the corresponding protected KEK in the list of KEKs (see step 01);

  2. Click on "Delete" and confirm the action;

If the operation was successful, the KEK has been deleted.

Only disabled (inactive) KEKs can be deleted. Protected KEKs can only be deleted if they are not protected by an HSM profile (see step 05).

P-KMS-TNT-04 - KMS-Tenant-Clients (create, change, delete)

Table 8. Profile: KMS Clients (create, change, delete)
profile

Designation

P-KMS-TNT-04 - KMS Clients (create, change, delete)

Purpose

A KMS tenant client accesses and uses the KMS APIs to interact with the KMS server on behalf of a KMS tenant. Access is allowed only after successful authentication. For authentication, the KMS server uses basic authentication and KMIP authentication with UserID+Password, also authentication with a client certificate and client authentication via Keycloak for the KMS-Crypto Interface.

The KMS tenant client users define the client name and credentials for accessing the KMS web services (KMIP API). The creation and management of KMS-Tenant client users is the responsibility of KMS-Tenant operators.

The description of the management of KMS tenant client users is the subject of P-KMS-TNT-04.

Responsibility

KMS-Tenant (Operator)

Working tool(s)

Browser, KMS-UI web application

Precondition/
Input

The KMS platform is up and running.

The KMS tenant user is logged into the KMS-UI application with their tenant user account.

Postcondition/
Output

  • A new KMS client has been created, or

  • an existing KMS client object has been modified, or

  • an existing KMS client object has been deleted.

Remarks

None
Table 9. Process steps: KMS-Clients (create, change, delete)
Process steps

01

Display the list of KMS clients:

  1. In the navigation menu (in the sidebar), select "KMS Clients" → "Show" (in the drop-down menu).

02

Create KMS client:

  1. Click on "Create new KMS Client" above the list of KMS clients (see step 01) (alternatively: "Create …​" → "KMS Client" or "Create" in the "KMS Client" drop-down menu in the sidebar) and confirm the process;

  2. Save the access data for the new KMS client securely:

    The access data will not be visible until you click on the corresponding field.

    Click on "Copy to Clipboard" to copy all access data and save them to the clipboard as follows:

    {
   "component":"KMS-Client",
   "username":"...",
   "password": "..."
}
The generated credentials must be passed to the responsible person in a secure manner. This is an organizational process that must be reliably established between the parties involved.

If the process is successful, a new KMS client is created.

03

Change KMS client:

  1. In the list of KMS clients (see step 01), select "Details" on the KMS client you want to edit;

  2. Now edit various attributes of the KMS client:

    1. To edit the Description or to activate/deactivate the KMS client select "Edit" under the "KMS Client information". After you have made the desired changes click on "Save";

    2. The Roles of the KMS client can be edited in the "Assigned KMS roles" area. To do this, click on "Edit" and make any desired changes. The available roles can be removed or added using the corresponding buttons for the KMS client. After completing your changes, click on the client name in the top left corner to return to the client detail view;

    3. You can edit and save the Authentication Types in the "Allowed Authentication Types" area. Depending on the authentication type being edited, you may need to securely store credentials again before proceeding; The following authentication options are possible disjointly:

      • Client-Auth using certificate, if this is selected, another section for generating a client certificate appears

      • Basic-Auth using username and password

      • KMIP-Auth using username and password

      • Login using Keycloak

    4. Username and Password are displayed but cannot be edited in this view;

    5. If the generate Client Certificate button is visible and pressed, a client certificate is automatically generated and on an extra page the client certificate is offered for download as a PKCS12, together with the password, once;

Take special care to ensure that the KMS client is activated and the preferred authentication strategy is selected. Otherwise, the user will not be able to log in.

04

Delete KMS client:

  1. In the list of KMS clients (see step 01), select "Details" on the KMS clients you want to delete;

  2. Check if the KMS client is deactivated (see step 03). Only deactivated clients can be deleted;

  3. Click on "Delete" and confirm the action.

Visibility of objects within a tenant by means of KMS-Tenant-Clients

A KMS-Tenant-Client is used by the tenant to access its objects stored in MTG-KMS. Separation of keys within a tenant for different KMS-Tenant-Clientss, so that they are not visible to other KMS-Tenant-Clients, is not provided. This can be achieved, for example, by using KMIP namespaces or by creating new tenants!

P-KMS-TNT-05 - Application Namespaces (create, change, delete)

Table 10. Profile: Application Namespaces (create, change, delete)
profile

Designation

P-KMS-TNT-05 - Application Namespaces (create, change, delete)

Purpose

MTG-KMS allows the user to define KMIP application namespaces for objects. These can be managed via the MTG-KMS Tenant interface.

Responsibility

KMS-Tenant (operator)

Working tool(s)

Browser, KMS-UI web application

Prerequisite/Input

The KMS platform is up and running.

The KMS Tenant user is logged into the KMS-UI application with their tenant user account.

Postcondition/Output

None

Remarks

None
Process steps

01

Display the list of application namespaces:

  1. In the navigation menu (in the sidebar), select "Application Namespaces" → "Show" (in the drop-down menu).

02

Create an application namespace:

  1. Click on "Create Application Namespace" above the list of application namespaces (see step 01) (alternatively: "Create …​" → "Application Namespaces" or "Create" in the "Application Namespaces" drop-down menu in the sidebar) and confirm the operation;

  2. Click on "Create application namespace";

  3. Enter the "Namespace" (mandatory field) and the "Data";

  4. Click "Apply" to create the application namespace.

03

Change an application namespace:

  1. In the list of application namespaces (see step 01), select "Details" on the application namespace you want to change;

  2. Click on "Edit";

  3. Change the value for "Data" ("Namespace" cannot be edited);

  4. Click on "Save";

04

Delete an application namespace:

  1. In the list of application namespaces (see step 01), select "Details" for the application namespace you want to delete;

  2. Click on "Delete" and confirm;

P-KMS-TNT-07 - CAs (show, delete)

Table 11. Profile: CAs (delete)
Profile

Designation

P-KMS-TNT-07 - CAs (delete)

Purpose

For a better overview, MTG KMS-UI provides an overview of linked issuer certification authorities (Issuer CAs). The displayed CAs were created by the Mini-CA and attached to the tenant by the KMS admin.

Responsibility

KMS-Tenant (Operator)

Working tool(s)

Browser, KMS-UI web application

Precondition/Input

The KMS platform is up and running.

The KMS tenant user is logged into the KMS-UI application with their tenant user account.

At least one issuer CA has been linked by the KMS admin for the tenant. Otherwise, the list is empty.

Postcondition/
Issue

None

Remarks

None
Process steps

01

Display the list of connected CAs:

  1. Select the "CAs" menu item in the navigation menu (in the sidebar).

02

Display the CA details:

  1. In the list of connected CAs (see step 01), click "Details" for the corresponding CA.

The following information is displayed for the CA:

  • CA information (Name, Subject DN, Valid to).

  • KMS-Client certificates (reference the CA)