Skip to main content

Edit a key management server (KMS)

Contributors ssantho3 netapp-perveilerk netapp-madkat netapp-lhalbert

You might need to edit the configuration of a key management server, for example, if a certificate is about to expire.

Before you begin
  1. Select CONFIGURATION > Security > Key management server.

    The Key management server page appears and shows all key management servers that have been configured.

  2. Select the KMS you want to edit, and select Actions > Edit.

    You can also edit a KMS by selecting the KMS name in the table and selecting Edit on the KMS details page.

  3. Optionally, update the details in Step 1 (KMS details) of the Edit a Key Management Server wizard.

    Field Description

    KMS name

    A descriptive name to help you identify this KMS. Must be between 1 and 64 characters.

    Key name

    The exact key alias for the StorageGRID client in the KMS. Must be between 1 and 255 characters.

    You only need to edit the key name in rare cases. For example, you must edit the key name if the alias is renamed in the KMS or if all versions of the previous key have been copied to the version history of the new alias.


    Never attempt to rotate a key by changing the key name (alias) for the KMS. Instead, rotate the key by updating the key version in the KMS software. StorageGRID requires all previously used key versions (as well as any future ones) to be accessible from the KMS with the same key alias. If you change the key alias for a configured KMS, StorageGRID might not be able to decrypt your data.

    Manages keys for

    If you are editing a site-specific KMS and you don't already have a default KMS, optionally select Sites not managed by another KMS (default KMS). This selection converts a site-specific KMS to the default KMS, which will apply to all sites that don't have a dedicated KMS and to any sites added in an expansion.

    Note: If you are editing a site-specific KMS, you can't select another site. If you are editing the default KMS, you can't select a specific site.


    The port the KMS server uses for Key Management Interoperability Protocol (KMIP) communications. Defaults to 5696, which is the KMIP standard port.


    The fully qualified domain name or IP address for the KMS.

    Note: The Subject Alternative Name (SAN) field of the server certificate must include the FQDN or IP address you enter here. Otherwise, StorageGRID will not be able to connect to the KMS or to all servers in a KMS cluster.

  4. If you are configuring a KMS cluster, select Add another hostname to add a hostname for each server in the cluster.

  5. Select Continue.

    Step 2 (Upload server certificate) of the Edit a Key Management Server wizard appears.

  6. If you need to replace the server certificate, select Browse and upload the new file.

  7. Select Continue.

    Step 3 (Upload client certificates) of the Edit a Key Management Server wizard appears.

  8. If you need to replace the client certificate and the client certificate private key, select Browse and upload the new files.

  9. Select Test and save.

    The connections between the key management server and all node-encrypted appliance nodes at the affected sites are tested. If all node connections are valid and the correct key is found on the KMS, the key management server is added to the table on the Key Management Server page.

  10. If an error message appears, review the message details, and select OK.

    For example, you might receive a 422: Unprocessable Entity error if the site you selected for this KMS is already managed by another KMS, or if a connection test failed.

  11. If you need to save the current configuration before resolving the connection errors, select Force save.

    Caution Selecting Force save saves the KMS configuration, but it does not test the external connection from each appliance to that KMS. If there is an issue with the configuration, you might not be able to reboot appliance nodes that have node encryption enabled at the affected site. You might lose access to your data until the issues are resolved.

    The KMS configuration is saved.

  12. Review the confirmation warning, and select OK if you are sure you want to force save the configuration.

    The KMS configuration is saved but the connection to the KMS is not tested.