DocsKnowledge BaseAPI Explorer
Documentation›Explore more›ZStack ZSphere›User GuideZVF
Document navigation

Key Provider Management

Key providers supply keys for VM encryption, disk encryption, and vTPM. ZSphere supports Standard Key Providers and Native Key Providers. A Standard Key Provider requires two-way trust with an external KMS. A Native Key Provider is provided by the platform and can be used without a third-party KMS.

When you create an encrypted resource or change the encryption state of a resource, the platform obtains keys from the default key provider. Before you use encryption, make sure the default key provider is connected and its key service is available. Back up the Native Key Provider before use so that you can restore the key service after a platform failure or rebuild.

Add a Standard Key Provider

You can add an external key server (KMS) to support various encryption capabilities of the system, thereby enhancing overall system security. The KMS must support the Key Management Interoperability Protocol (KMIP) 1.1 or later.

Before you begin

Make sure the platform is installed with a valid Advanced Edition license.

Procedure

  1. In the navigation pane, select Inventory > VM and Host.
  2. Select the root node.
  3. On the root node details page, click Key Providers.
  4. On the Key Providers tab, click Add Key Provider.
  5. In the Add Key Provider dialog, configure the following options:
    Option Description
    Name Enter a name for the key provider.
    Note: The name of each key provider serves as its identifier. Ensure the name is globally unique.
    Description Enter a brief description for the key provider.
    Type Select Standard Key Provider.
    IP Address/Domain Name Enter the IP address or domain name of the KMS.
    Port Enter the connection port of the KMS. The default port is 5696.
    Password Protection Some KMS systems allow you to isolate encryption keys used by different users or groups by specifying a username and password. Enable this option and enter the corresponding username and password.
  6. After you confirm the configuration details are correct, click OK.
  7. Click Trust.
    After the key provider is added successfully, its status shows as "Connected | Not Trusted by KMS".

What to do next

Use KMS Certificate and Private Key to Make KMS Trust ZSphere

Some KMS vendors require you to upload the KMS server certificate and private key to ZSphere.

Procedure

  1. Navigate to the Key Providers page.
  2. Locate the standard key provider with which you want to establish trust, and click Actions > Establish Trust > Make KMS Trust the Platform.
  3. In the Make KMS Trust the Platform dialog, select KMS Certificate and Private Key as the trust method.
  4. Click Next.
  5. Upload the certificate and private key files you received from the KMS, or paste the certificate and private key content into the text box.
  6. Click OK.

What to do next

To establish two-way trust, see Make ZSphere Trust the KMS.

Use the New Certificate Signing Request (CSR) to Make KMS Trust ZSphere

Some KMS vendors require ZSphere to generate a Certificate Signing Request (CSR) and submit the CSR to the KMS. The KMS signs the CSR and returns a signed certificate. You must upload the signed certificate back to ZSphere to establish trust.

Procedure

  1. Navigate to the Key Providers page.
  2. Locate the standard key provider with which you want to establish trust, and click Actions > Establish Trust > Make KMS Trust the Platform.
  3. In the Make KMS Trust the Platform dialog, select New Certificate Signing Request (CSR) as the trust method.
  4. Click Next.
  5. Click Copy or Download to copy the entire content from the text box or save it as a file.
    Use Generate New CSR only when you explicitly need to create a new CSR.
  6. Click OK.
  7. Log in to the KMS and submit the CSR according to the KMS requirements.
  8. After you receive the certificate signed by the KMS, click Actions > Establish Trust > Upload Signed CSR Certificate again.
  9. Paste the signed certificate into the text box, or click Upload File to upload it.

What to do next

To establish two-way trust, see Make ZSphere Trust the KMS.

Make ZSphere Trust the KMS

If you skipped the step of trusting the KMS when you added the standard key provider, you must establish two-way trust after the KMS trusts ZSphere.

Procedure

  1. Navigate to the Key Providers page.
  2. Locate the standard key provider with which you want to establish trust, and click Actions > Establish Trust.
  3. Select one of the following options from the Establish Trust menu.
    • Make the Platform Trust KMS: In the Make the Platform Trust KMS dialog, click Trust.
    • Upload KMS Certificate: In the Upload KMS Certificate dialog, upload a file or paste the certificate content into the text box. Then click OK.

Delete a Standard Key Provider

Before you begin

  • When multiple key providers exist, the default key provider cannot be deleted. Set another key provider as the default first, and then perform the deletion.
  • To preserve encrypted resources that depend on this key provider, perform a global Rekey operation before deletion. The operation uses a new KEK from the current default key provider to rewrap the DEKs of the encrypted resources.

Procedure

  1. In the navigation pane, select Inventory > VM and Host.
  2. Select the root node.
  3. On the root node details page, click Key Providers.
  4. On the Key Providers tab, select the standard key provider you want to delete, and then click Actions > Delete.
    Note: After you delete a key provider, resources that depend on it, such as vTPM-enabled VMs, encrypted VMs, and encrypted disks, are locked and become unavailable.
  5. Read the risk warning, enter the confirmation information, and click OK.

Use the Thales Key Provider

About this task

  1. Add the Thales key provider in ZSphere
  2. Create a localhost user in Thales and add it to the admin group
  3. (Optional) Use the New Certificate Signing Request (CSR) method to make Thales trust ZSphere
  4. (Optional) Use the KMS certificate and private key method to make Thales trust ZSphere

Procedure

  1. Add the Thales key provider in ZSphere.
    For detailed steps, see Add a Standard Key Provider.
  2. Create a localhost user in Thales and add it to the admin group.
    1. Log in to Thales.
    2. Click Access Management > Users > Add User.
      Figure 1. Add a User


    3. Create the localhost user.
      Figure 2. Create the localhost User


    4. Click the user name to go to its details page.
    5. Expand the GROUP MEMBERSHIP section, and then click Add Group.
      Figure 3. Add the User to a Group


    6. In the Add member to group(s) dialog, select admin, and then click Add Group.
  3. (Optional) Use the New Certificate Signing Request (CSR) method to make Thales trust ZSphere.
    1. Log in to ZSphere.
    2. Navigate to the Key Providers page.
    3. Locate the Thales standard key provider you added, and click Actions > Establish Trust > Make the KMS Trust ZSphere.
    4. In the Make the KMS Trust ZSphere dialog, select New Certificate Signing Request (CSR) as the trust method.
    5. Click Next.
    6. Copy the entire CSR content.
    7. Log in to Thales.
    8. Click Products > KMIP.
      Figure 4. Access the KMIP Module


    9. Click Client Profile > Add Profile.
      Figure 5. Add a Profile


    10. In the Add Profile dialog, set the profile basic information, paste the CSR information, and then click Save.
      Figure 6. Configure the Profile


    11. Click Registration Token > New Registration Token.
      Figure 7. New Registration Token


    12. In the Create New Registration Token dialog, follow the wizard to complete the configuration.
      • In step 3 Select Profile, select the profile you created earlier.
      • In step 4 Create Token, copy the generated token.
      Figure 8. Create a Token


    13. Click Registered Clients > Add Client.
      Figure 9. Add a Client


    14. In the Add Client dialog, set the client name, paste the registration token, and then click Save.
      Figure 10. Configure the Client


    15. After saving successfully, click Save CSR and Save Certificate to download the CSR and certificate.
      Figure 11. Download the CSR and Certificate


    16. Log in to ZSphere.
    17. Navigate to the Key Providers page, and then click Actions > Establish Trust > Upload Signed CSR Certificate.
    18. Upload the certificate you downloaded from Thales.
  4. (Optional) Use the KMS certificate and private key method to make Thales trust ZSphere.
    1. Log in to Thales.
    2. Click Products > KMIP.
      Figure 12. Access the KMIP Module


    3. Click Client Profile > Add Profile.
      Figure 13. Add a Profile


    4. In the Add Profile dialog, set the profile name, and then click Save.
      Figure 14. Add a Profile


    5. Click Registration Token > New Registration Token.
      Figure 15. New Registration Token


    6. In the Create New Registration Token dialog, follow the wizard to complete the configuration.
      • In step 3 Select Profile, select the profile you created earlier.
      • In step 4 Create Token, copy the generated token.
      Figure 16. Create a Token


    7. Click Registered Clients > Add Client.
      Figure 17. Add a Client


    8. In the Add Client dialog, set the client name, paste the registration token, and then click Save.
      Figure 18. Configure the Client


    9. After saving successfully, click Save Certificate and Save Private Key to download the certificate and private key.
      Figure 19. Download the Certificate and Private Key


    10. Log in to ZSphere.
    11. Navigate to the Key Providers page.
    12. Locate the Thales standard key provider you added, and click Actions > Establish Trust > Make the KMS Trust ZSphere.
    13. In the Make the KMS Trust ZSphere dialog, select KMS Certificate and Private Key as the trust method.
    14. Click Next.
    15. Upload the KMS certificate and private key you downloaded from Thales.
    16. Click OK.

Use the HashiCorp Key Provider

About this task

  1. Add the HashiCorp key provider in ZSphere
  2. (Optional) Use the KMS certificate and private key method to make HashiCorp trust ZSphere
  3. (Optional) Use the New Certificate Signing Request (CSR) method to make HashiCorp trust ZSphere

Procedure

  1. Add the HashiCorp key provider in ZSphere.
    For detailed steps, see Add a Standard Key Provider.
  2. (Optional) Use the KMS certificate and private key method to make HashiCorp trust ZSphere.
    1. Log in to HashiCorp.
    2. Click Vault > Secrets Engines.
    3. On the Secrets Engines page, click kmip to access the KMIP module.
      Figure 20. Access the KMIP Module


    4. On the kmip page, click Create scope to create a scope or enter an existing one.
      Figure 21. Create or Enter an Existing Scope


    5. On the scope details page, click Create role to create a role.
    6. On the Create a Role page, set the role name and complete the TLS configuration by referring to the example.
      Figure 22. Create a Role


    7. After you create the role, click the role to go to its details page, and then click Generate credentials.
    8. On the Generate Credentials page, select pem as the certificate format, and then click Save.
      Figure 23. Generate a Certificate


    9. Copy the certificate and private key.
      Figure 24. Copy the Certificate and Private Key


    10. Log in to ZSphere.
    11. Navigate to the Key Providers page.
    12. Locate the HashiCorp standard key provider you added, and click Actions > Establish Trust > Make the KMS Trust ZSphere.
    13. In the Make the KMS Trust ZSphere dialog, select KMS Certificate and Private Key as the trust method.
    14. Click Next.
    15. Paste the KMS certificate and private key you copied from HashiCorp.
    16. Click OK.
  3. (Optional) Use the New Certificate Signing Request (CSR) method to make HashiCorp trust ZSphere.
    1. Log in to the HashiCorp system.
    2. Run vault login and enter the token.
    3. Generate the CSR: 
      vault write -format=json kmip/scope/test/role/admin/credential/sign csr="$(cat csr.pem)" | jq -r '.data.certificate' > client.crt
    4. Log in to ZSphere.
    5. Navigate to the Key Providers page, and then click Actions > Establish Trust > Upload Signed CSR Certificate.
    6. Upload the obtained client.crt certificate.

Add a Native Key Provider

ZSphere provides a native key provider that allows you to enable encryption-related features without a third-party KMS.

Procedure

  1. In the navigation pane, select Inventory > VM and Host.
  2. Select the root node.
  3. On the root node details page, click Key Providers.
  4. On the Key Providers tab, click Add Key Provider.
  5. In the Add Key Provider dialog, configure the following options:
    Option Description
    Name Enter a name for the key provider.
    Note: The name of each key provider serves as its identifier. Ensure the name is globally unique.
    Description Enter a brief description for the key provider.
    Type Select Native Key Provider.
  6. Click OK.
    After the key provider is added successfully, its status shows as "Not Backed Up".

What to do next

After you add a native key provider, you must back it up before use. For more information, see Back Up the Native Key Provider.

Back Up the Native Key Provider

The Native Key Provider is stored only in ZSphere. If ZSphere fails or must be rebuilt, its keys are lost and encrypted resources that depend on the provider become unavailable. Back up the Native Key Provider so that you can restore the key service and regain access to the encrypted resources after rebuilding ZSphere.

Procedure

  1. In the navigation pane, select Inventory > VM and Host.
  2. Select the root node.
  3. On the root node details page, click Key Providers.
  4. On the Key Providers tab, select the native key provider you want to back up.
    For key providers that are not yet backed up, the status shows as "Not Backed Up".
  5. Click Actions > Back Up.
  6. In the Back Up Key Provider dialog, select the backup mode as needed.
    Option Description
    Without Password Protection
    Note: Without password protection, the configuration data and the virtual machines encrypted with this key provider face potential security risks.
    Password Protection Enter and confirm the password.
    Note:

    Store the password in a safe place. The platform cannot access or recover the password you set. Make sure this password is securely saved, as it will be required to restore the Native Key Provider configuration in case of disaster.

    If you forget or lose the password:

    • You cannot restore the key provider.
    • You cannot access encrypted resources that depend on this key provider, such as vTPM-enabled VMs, encrypted VMs, and encrypted disks.
  7. Click OK.
    The backup file is downloaded through your browser. Save the backup file in a secure location.

Restore the Native Key Provider

Before you begin

  • You have prepared the backup file of the native key provider.
  • If you set password protection for the backup file when you backed up the key provider, prepare the password for the backup file.
  • Ensure that no key provider with the same name exists on the platform.

Procedure

  1. In the navigation pane, select Inventory > VM and Host.
  2. Select the root node.
  3. On the root node details page, click Key Providers.
  4. On the Key Providers tab, click Actions > Restore.
  5. In the Restore Key Provider dialog, upload the backup file.
  6. (Optional) If the backup file is password-protected, enter the password.
  7. Click Next.
  8. Confirm the information of the key provider to restore, and then click OK.

Delete the Native Key Provider

Before you begin

  • If you want to keep the key provider for future use, back it up first.
  • To preserve encrypted resources that depend on this key provider, perform a global Rekey operation before deletion. The operation uses a new KEK from the current default key provider to rewrap the DEKs of the encrypted resources.

Procedure

  1. In the navigation pane, select Inventory > VM and Host.
  2. Select the root node.
  3. On the root node details page, click Key Providers.
  4. On the Key Providers tab, select the native key provider you want to delete, and then click Actions > Delete.
    Note:
    • After deletion, resources that depend on this key provider, such as vTPM-enabled VMs, encrypted VMs, and encrypted disks, are locked and become unavailable.
    • The key provider is permanently deleted from the platform and cannot be recovered. Proceed with caution.
  5. Read the risk warning, enter the confirmation information, and click OK.

Rekey

To meet requirements such as periodic key rotation, suspected key compromise, or security compliance, perform a shallow rekey on encrypted resources across the platform. This operation uses a new key encryption key (KEK) from the current default key provider to rewrap the data encryption keys (DEKs). It does not replace the DEKs or re-encrypt the actual workload data.

Before you begin

  • Make sure that the current default key provider is connected and its key service is available.
  • Make sure that the key providers and keys currently protecting encrypted resources across the platform are available.

Procedure

  1. In the navigation pane, select Inventory > VM and Host.
  2. Select the root node.
  3. On the root node details page, click Key Providers.
  4. On the Key Providers tab, click Actions > Rekey.
  5. In the Rekey dialog, click OK.
    The platform completes a shallow rekey by using a new KEK from the current default key provider to rewrap the DEKs of encrypted resources, including VMs, disks, disk snapshots, vTPMs, and encrypted VMs and disks in the Recycle Bin. The actual workload data is not re-encrypted.
PreviousAccessKey ManagementNextVM Encryption
User Guide | ZStack ZSphere · ZVF | ZStack Resource Center