Add a key management server (KMS)

Contributors netapp-madkat netapp-perveilerk

You use the StorageGRID Key Management Server wizard to add each KMS or KMS cluster.

What you’ll need
About this task

If possible, configure any site-specific key management servers before configuring a default KMS that applies to all sites not managed by another KMS. If you create the default KMS first, all node-encrypted appliances in the grid will be encrypted by the default KMS. If you want to create a site-specific KMS later, you must first copy the current version of the encryption key from the default KMS to the new KMS. See Considerations for changing the KMS for a site for details.

Step 1: Enter KMS Details

In Step 1 (Enter KMS Details) of the Add a Key Management Server wizard, you provide details about the KMS or KMS cluster.

Steps
  1. Select CONFIGURATION > Security > Key management server.

    The Key Management Server page appears with the Configuration Details tab selected.

    KMS Configuration Details No KMS
  2. Select Create.

    Step 1 (Enter KMS Details) of the Add a Key Management Server wizard appears.

    KMS Step 1 Enter KMS Details
  3. Enter the following information for the KMS and the StorageGRID client you configured in that KMS.

    Field Description

    KMS Display 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.

    Manages keys for

    The StorageGRID site that will be associated with this KMS. If possible, you should configure any site-specific key management servers before configuring a default KMS that applies to all sites not managed by another KMS.

    • Select a site if this KMS will manage encryption keys for the appliance nodes at a specific site.

    • Select Sites not managed by another KMS (default KMS) to configure a default KMS that will apply to any sites that do not have a dedicated KMS and to any sites you add in subsequent expansions.

      Note: A validation error will occur when you save the KMS configuration if you select a site that was previously encrypted by the default KMS but you did not provide the current version of original encryption key to the new KMS.

    Port

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

    Hostname

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

    Note: The 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 using a KMS cluster, select the plus sign Icon Plus Sign to add a hostname for each server in the cluster.

  5. Select Next.

Step 2: Upload Server Certificate

In Step 2 (Upload Server Certificate) of the Add a Key Management Server wizard, you upload the server certificate (or certificate bundle) for the KMS. The server certificate allows the external KMS to authenticate itself to StorageGRID.

Steps
  1. From Step 2 (Upload Server Certificate), browse to the location of the saved server certificate or certificate bundle.

    KMS Step 2 Upload Server Certificate
  2. Upload the certificate file.

    The server certificate metadata appears.

    kms step 2 server certificate metadata
    Note If you uploaded a certificate bundle, the metadata for each certificate appears on its own tab.
  3. Select Next.

Step 3: Upload Client Certificates

In Step 3 (Upload Client Certificates) of the Add a Key Management Server wizard, you upload the client certificate and the client certificate private key. The client certificate allows StorageGRID to authenticate itself to the KMS.

Steps
  1. From Step 3 (Upload Client Certificates), browse to the location of the client certificate.

    KMS Step 3 Upload Client Certificate
  2. Upload the client certificate file.

    The client certificate metadata appears.

  3. Browse to the location of the private key for the client certificate.

  4. Upload the private key file.

    The metadata for the client certificate and the client certificate private key appear.

    KMS Step 3 Client Certificate Metadata
  5. Select Save.

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

    Note Immediately after you add a KMS, the certificate status on the Key Management Server page appears as Unknown. It might take StorageGRID as long as 30 minutes to get the actual status of each certificate. You must refresh your web browser to see the current status.
  6. If an error message appears when you select Save, review the message details and then select OK.

    For example, you might receive a 422: Unprocessable Entity error if a connection test failed.

  7. If you need to save the current configuration without testing the external connection, select Force Save.

    KMS Force Save
    Important 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.
  8. Review the confirmation warning, and select OK if you are sure you want to force save the configuration.

    KMS Force Save Warning

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