Business Processes KMS Crypto

This page describes the processes and tasks that the KMS Client user performs through the KMS UI application using "KMS Crypto" (also "KMS Crypto API", "KMS Tenant Client" or "KMS Client") to create and manage cryptographic objects.

"KMS Crypto" provides methods for the following tasks:

  • Generate and manage cryptographic objects

    • Secret key for symmetric cryptography

    • Secret data for secret value sharing

    • Key pair (public key + private key) for public key cryptography

  • Use cryptographic objects within the application (decrypt/encrypt or sign/verify)

  • Manage own account (keycloak etc.)

The necessary identification and authentication towards the "KMS Crypto" application (KMS Crypto API, KMS (Tenant) Client) is described in the following process steps:

Table 1. process steps: Login to KMS Crypto
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 for your KMS client by the 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 Crypto application.

03

It is recommended to change the randomly assigned client 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 Crypto" 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 Crypto" button.

05

Other functionalities:

  • Configure authentication method

  • Switch application

  • Log out from the "KMS Crypto" 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 on "Logout" to log out of the "KMS Crypto" 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-CRP-01 - Cryptographic Objects (generate, activate, delete)

Table 2. Profile: Cryptographic Objects (generate, activate, delete)
Profile

Designation

P-KMS-CRP-01 - Cryptographic Objects (generate, activate, delete)

Purpose

The use of secure keys is important for the application of secure cryptography. The secure generation of these cryptographic objects and their management is performed by the KMS client user, by means of the "KMS Crypto" application.

To this end, any user of "KMS Crypto" can securely and reliably generate cryptographic objects such as keys and also specify a wide range of details.

Available key types are secret keys for symmetric cryptography, as well as key pairs for public-key encryption.

The KMS client user is responsible for the creation and management of cryptographic objects.

The description of the administration of cryptographic objects is the subject of P-KMS-CRP-01.

Responsibility

KMS-Client

Working tool(s)

Browser, KMS-UI web application

Precondition/
Input

The KMS platform is up and running.

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

Tenant and client are set up.

Postcondition/
Output

  • A new cryptographic object has been generated, or

  • an existing cryptographic object has been modified, or

  • an existing cryptographic object was deleted.

Remarks

None
Table 3. Process steps: Cryptographic objects (generate, activate, delete)
Process steps

01

Display the list of cryptographic objects:

  1. In the navigation menu (in the sidebar), select "Cryptographic Objects" → "Show" (in the drop-down menu). The list shows secret keys, key pairs and certificates.

02

Generate secret key:

  1. Click on "Create …​" → "Secret Key" or "Generate Secret Key" in the "Cryptographic Objects" drop-down menu in the sidebar;

  2. Enter a "Name" for the key and select "Cryptographic Algorithm", "Cryptographic Usage Mask" and "Cryptographic Length";

  3. By clicking the checkbox at "Extractable" you can specify whether the get operation can be used on the key;

  4. By clicking the checkbox at "Sensitive" you can specify whether the get operation can be used on the key. When enabled, it can only be used if the key is a wrapped by another key;

  5. Click on "Apply" and the secret key will be generated. Further information will be displayed afterwards.

The new key is activated by default.

03

Generate key pair:

  1. Click on "Create …​" → "Key Pair" or "Generate Key Pair" in the "Cryptographic Objects" drop-down menu in the sidebar;

  2. Enter a "Name" for the key pair and select "Cryptographic Algorithm", "Cryptographic Usage Mask" and (depending on the algorithm) "Cryptographic Length", "EC Curve" or "ED Curve";

  3. By clicking the checkbox at "Extractable" you can specify whether the get operation can be used on the key;

  4. By clicking the checkbox at "Sensitive" you can specify whether the get operation can be used on the key. When enabled, it can only be used if the key is a wrapped by another key;

  5. Click on "Apply" and the key pair is generated. Further information will be displayed afterwards.

The keys of the generated key pair are enabled by default. In the list of cryptographic objects (see step 01) they are listed as two keys (private key, public key).

04

Generate secret data:

  1. Click on "Create …​" → "Secret Data" or "Generate Data" in the "Cryptographic Objects" drop-down menu in the sidebar;

  2. Enter a "Name" for the secret data and select "Secret Data Type" and "Key Format Type" (depending on the secret data type the available options change), "Cryptographic Usage Mask" and "Cryptographic Length".

  3. By clicking the checkbox at "Extractable" you can specify whether the get operation can be used on the secret data;

  4. By clicking the checkbox at "Sensitive" you can specify whether the get operation can be used on the key. When enabled, it can only be used if the key is a wrapped by another key;

  5. Click on "Apply" and the secret data will be generated. Further information will be displayed afterwards.

The new secret data is activated by default.

05

Modify and manage cryptographic objects:

  1. Click on the button with three dots and then on "Details" for the corresponding object in the list of cryptographic objects (see step 01);

  2. The modification options vary depending on the type of object:

    • For secret keys (symmetric keys): "Activate", "Deactivate", "Reactivate" (if it is enabled for the KMS Tenant);

    • For secret data : "Activate", "Deactivate", "Reactivate" (if it is enabled for the KMS Tenant);

    • For private keys of key pairs: "Activate", "Deactivate", "Reactivate" (if it is enabled for the KMS Tenant), "Delete". See below for more information;

    • For public keys of key pairs: "Generate PKCS11 ID", "Create CSR", "Import certificate", "Download public key (.pem)", "Activate", "Deactivate", "Reactivate" (if it is enabled for the KMS Tenant), "Delete". See below for more information;

    • For authentication certificates: Managed by the Tenant KMS Client in Tenant UI.

    • For KMIP certificates: "Activate", "Deactivate", "Reactivate" (if it is enabled for the KMS Tenant), "Delete", "Revoke". See below for more information;

  3. Additional management options for public keys of key pairs are:

    • Generate PKCS11 ID: Adds a PKCS11 ID to the public key information of a key pair (in Hex and Base 64).

    • Create CSR: Allows to create a new PKC10 request to sign the key pair:

      1. Clicking the "Create CSR" button in the key pair detail view takes you to the PKCS10 request creation view;

      2. In addition to the mandatory information for name and signature algorithm, you can specify country, email, organization, organizational unit, domains and ips;

      3. Click "Apply" to create the PKCS10 request.

    • Import Certificate: Allows to upload a signed certificate for the public key.

    • Download Public Key (.pem): Allows to download the public key as a .pem file.

  4. Management options for certificates are:

    • Download (.pem): Allows to download the certificate as a .pem file.

06

Use cryptographic objects:

Secret Key (symmetric Key):

  • It is possible to use symmetric secret keys for encryption and decryption within the "KMS Crypto" application.

    1. Click on the button with three dots and then on "Details" for the corresponding object in the list of cryptographic objects (see step 01);

    2. The usage options are "Encrypt" and "Decrypt", and they can be accessed with the corresponding buttons.

  • Encrypt: You can encrypt by selecting a block cipher mode (CBC, GCM), a padding method and (for GCM) a tag length with the corresponding drop-down menus.

    • Data can be either entered as text or uploaded as file.

    • After confirming the encrypted data is displayed and can be copied as JSON containing all important information.

  • Decrypt: You can decrypt previously encrypted data by selecting the correct block cipher mode, padding method, tag length, IV/counter/nonce and authenticated encryption tag for the used encryption method with the corresponding drop-down menus.

    • Data can be either entered as text or uploaded as file.

    • After confirming the decrypted data is displayed.

Secret Data :

  • It is possible to use secret data for derivation of keys within the "KMS Crypto" application.

    1. Click on the button with three dots and then on "Details" for the corresponding object in the list of cryptographic objects (see step 01);

Key Pair (asymmetric private and public key):

  • It is possible to use asymmetric private keys for signing and public keys for verifying signatures within the "KMS Crypto" application.

    1. Click on the button with three dots and then on "Details" for the corresponding object in the list of cryptographic objects (see step 01);

    2. The usage options are "Sign" (private key) and "Verify" (public key), and they can be accessed with the corresponding buttons.

  • Sign: You can sign by selecting a digital signature algorithm (various forms of SHA with RSA or SHA with ECDSA) from the corresponding drop-down menu.

    • Data can be entered as text or uploaded as file.

    • After confirming the signature data is displayed and can be copied as JSON containing all important information.

  • Verify: You can verify previously encrypted data by selecting the correct digital signature algorithm from the drop-down menu.

    • The data that was to be signed can be entered as text or uploaded as file and the corresponding signature data can be entered as text.

    • After confirming, it is displayed weather the signature is valid or invalid for the respective key, data and algorithm.

KMIP Certificate :

  • It is possible to revoke a KMIP certificate.

    1. Click on the button with three dots and then on "Details" for the corresponding object in the list of cryptographic objects (see step 01);

    2. The "Revoke" usage option can be accessed with the corresponding button.

  • Revoke: You can revoke a certificate by selecting a revocation reason.

    • The suspended date input is available when selecting Key Compromise or CA Compromise for the revocation reason.

    • After confirming, the certificate will be revoked and depending on the revocation reason it will be either deactivated or compromised.

07

Activate a cryptographic object:

  1. In the list of cryptographic objects (see step 01), change the cryptographic object (see step 03) that should be activated. Make sure that it is pre-active;

  2. Click "Activate" and confirm the action.

If the operation was successful, the cryptographic object has been activated.

Only pre-active cryptographic objects can be activated (see step 03).
For the Key Pair (asymmetric private and public key) and KMIP Certificate when there are linked cryptographic objects you can select to manage them along when activating.

08

Deactivate a cryptographic object:

  1. In the list of cryptographic objects (see step 01), change the cryptographic object (see step 03) that should be reactivated. Make sure that it is active;

  2. Click "Deactivate" and confirm the action.

If the operation was successful, the cryptographic object has been deactivated.

Only active cryptographic objects can be deactivated (see step 03).
For the Key Pair (asymmetric private and public key) and KMIP Certificate when there are linked cryptographic objects you can select to manage them along when deactivating.

09

Reactivate a cryptographic object:

  1. In the list of cryptographic objects (see step 01), change the cryptographic object (see step 03) that should be reactivated. Make sure that it is deactivated;

  2. Click "Reactivate" and confirm the action.

If the operation was successful, the cryptographic object has been active again.

Only deactivated cryptographic objects can be reactivated (see step 03).
For the Key Pair (asymmetric private and public key) and KMIP Certificate when there are linked cryptographic objects you can select to manage them along when reactivating.

10

Delete a cryptographic object:

  1. In the list of cryptographic objects (see step 01), change the cryptographic object (see step 03) that should be deleted. Make sure that it is deactivated;

  2. Click "Delete" and confirm the action.

If the operation was successful, the cryptographic object has been deleted.

Only deactivated cryptographic objects can be deleted (see step 03).
Symmetric Keys that are deactivated but not deleted, can still be used to decrypt previously encrypted data. Likewise, deactivated public keys can still be used to verify old signatures.
For the Key Pair (asymmetric private and public key) and KMIP Certificate when there are linked cryptographic objects you can select to manage them along when deleting.