For the Key Provider Service to connect to a key provider, you must create a trusted key provider then configure a trust setup between the vSphere Trust Authority Cluster and the key server (KMS). For most KMIP-compliant key servers, this configuration involves setting up client and server certificates.

What was previously called a KMS Cluster in vSphere 6.7 is now called a key provider in vSphere 7.0 and later. For more information about key providers, see What Is the vSphere Trust Authority Key Provider Service.

In a production environment, you can create multiple key providers. By creating multiple key providers, you can address how to manage your deployment based on company organization, different business units or customers, and so on.

If you are following these tasks in order, you are still connected to the vCenter Server of the vSphere Trust Authority Cluster.

Prerequisites

Procedure

  1. Ensure that you are connected to the vCenter Server of the Trust Authority Cluster. For example, you can enter $global:defaultviservers to show all the connected servers.
  2. (Optional) If necessary, you can run the following commands to ensure that you are connected to the vCenter Server of the Trust Authority Cluster. 
    Disconnect-VIServer -server * -Confirm:$false
Connect-VIServer -server TrustAuthorityCluster_VC_ip_address -User trust_admin_user -Password 'password'
  3. To create the trusted key provider, run the New-TrustAuthorityKeyProvider cmdlet.
    For example, this command uses 1 for the PrimaryKeyID and the name clkp. If you are following these tasks in order, you previously assigned Get-TrustAuthorityCluster information to a variable (for example, $vTA = Get-TrustAuthorityCluster 'vTA Cluster'). 
    New-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA -PrimaryKeyId 1 -Name clkp -KmipServerAddress ip_address
    The PrimaryKeyID is normally a key ID that comes from the key server in the form of a UUID. Do not use the key name for PrimaryKeyID. The PrimaryKeyID value is vendor-dependent. See your key server documentation. The New-TrustAuthorityKeyProvider cmdlet can take other options, such as KmipServerPort, ProxyAddress, and ProxyPort. See the New-TrustAuthorityKeyProvider Help system for more information.

    Each logical key provider, regardless of its type (Standard, Trusted, and Native Key Provider), must have a unique name across all vCenter Server systems.

    For more information, see Key Provider Naming.

    Note: To add multiple key servers to the key provider, use the Add-TrustAuthorityKeyProviderServer cmdlet.
    The key provider information is displayed.
  4. Establish the trusted connection so that the key server trusts the trusted key provider. The exact process depends on the certificates that the key server accepts, and on your company policy. Select the option appropriate for your server and finish the steps.
    Option See
    Upload Client Certificate Upload the Client Certificate to Establish a Trusted Key Provider Trusted Connection.
    Upload KMS certificate and private key Upload the Certificate and Private Key to Establish a Trusted Key Provider Trusted Connection.
    New Certificate Signing Request Create a Certificate Signing Request to Establish a Trusted Key Provider Trusted Connection.
  5. Finish the trust setup by uploading a key server certificate so that the trusted key provider trusts the key server.
    1. Assign the Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA information to a variable.
      For example: 
      $kp = Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA

      This variable obtains the trusted key providers in the given Trust Authority Cluster, in this case, $vTA.

      Note: If you have more than one trusted key provider, use commands similar to the following to select the one you want: 
      Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA
<The trusted key providers listing is displayed.>
$kp = Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA | Select-Object -Last 1

      Using Select-Object -Last 1 selects the last trusted key provider in the list.

    2. To get the key server server certificate, run the Get-TrustAuthorityKeyProviderServerCertificate command.
      For example: 
      Get-TrustAuthorityKeyProviderServerCertificate -KeyProviderServer $kp.KeyProviderServers
      The server certificate information is displayed. Initially, the certificate is not trusted, so the Trusted state is False. If you have more than one key server configured, a list of certificates is returned. Verify and add each certificate using the following instructions.
    3. Before trusting the certificate, assign Get-TrustAuthorityKeyProviderServerCertificate -KeyProviderServer $kp.KeyProviderServers information to a variable (for example, cert), and run the $cert.Certificate.ToString() command and verify the output.
      For example: 
      $cert = Get-TrustAuthorityKeyProviderServerCertificate -KeyProviderServer $kp.KeyProviderServers
$cert.Certificate.ToString()
      The certificate information is displayed, including Subject, Issuer, and other information.
    4. To add the KMIP server certificate to the trusted key provider, run Add-TrustAuthorityKeyProviderServerCertificate.
      For example: 
      Add-TrustAuthorityKeyProviderServerCertificate -ServerCertificate $cert
      The certificate information is displayed and the Trusted state is now True.
  6. Verify the status of the key provider.
    1. To refresh the key provider status, reassign the $kp variable.
      For example: 
      $kp = Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA
      Note: If you have more than one trusted key provider, use commands similar to the following to select the one you want: 
      Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA
<The trusted key providers listing is displayed.>
$kp = Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA | Select-Object -Last 1

      Using Select-Object -Last 1 selects the last trusted key provider in the list.

    2. Run the $kp.Status command to get the key provider status.
      For example: 
      $kp.Status
      Note: The status can take a few minutes to be refreshed. To view the status, reassign the $kp variable and rerun the $kp.Status command.
    A Health status of Ok indicates that the key provider is running correctly.

Results

The trusted key provider is created and has established trust with the key server.

Example: Create the Key Provider on the Trust Authority Cluster

This example shows how to use PowerCLI to create the trusted key provider on the Trust Authority Cluster. It assumes that you are connected to the vCenter Server of the Trust Authority Cluster as the Trust Authority administrator. It also uses a certificate signed by the key server vendor after submitting a CSR to the vendor.

The following table shows the example components and values that are used.

Table 1. Example vSphere Trust Authority Setup
Component Value
Variable $vTA Get-TrustAuthorityCluster 'vTA Cluster'
Variable $kp Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA
Variable $cert Get-TrustAuthorityKeyProviderServerCertificate -KeyProviderServer $kp.KeyProviderServers
vCenter Server for Trust Authority Cluster 192.168.210.22
KMIP-compliant key server 192.168.110.91
KMIP-compliant key server user vcqekmip
Trust Authority Cluster name vTA Cluster
Trust Authority administrator [email protected] 
PS C:\Users\Administrator.CORP> Disconnect-VIServer -server * -Confirm:$false
PS C:\Users\Administrator.CORP> Connect-VIServer -server 192.168.210.22 -User [email protected] -Password 'VMware1!'

PS C:\Users\Administrator.CORP> New-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA -PrimaryKeyId 8 -Name clkp -KmipServerAddress 192.168.110.91
Name                 PrimaryKeyId         Type       TrustAuthorityClusterId
----                 ------------         ----       -----------------------
clkp                 8                    KMIP       TrustAuthorityCluster-domain-c8

PS C:\Users\Administrator.CORP> New-TrustAuthorityKeyProviderClientCertificate -KeyProvider $kp
<Export the client certificate when you need to use it.>
PS C:\Users\Administrator.CORP> Export-TrustAuthorityKeyProviderClientCertificate -KeyProvider $kp -FilePath clientcert.pem

PS C:\Users\Administrator.CORP> $kp = Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA
PS C:\Users\Administrator.CORP> Get-TrustAuthorityKeyProviderServerCertificate -KeyProviderServer $kp.KeyProviderServers

Certificate                              Trusted    KeyProviderServerId       KeyProviderId
-----------                              -------    -------------------       -------------
[Subject]...                             False      domain-c8-clkp:192.16.... domain-c8-clkp

PS C:\WINDOWS\system32> $cert.Certificate.ToString()
[Subject]
  E=<domain>, CN=<IP address>, OU=VMware Engineering, O=VMware, L=Palo Alto, S=California, C=US

[Issuer]
  O=<host>.eng.vmware.com, C=US, DC=local, DC=vsphere, CN=CA

[Serial Number]
  00CEF192BBF9D80C9F

[Not Before]
  8/10/2015 4:16:12 PM

[Not After]
  8/9/2020 4:16:12 PM

[Thumbprint]
  C44068C124C057A3D07F51DCF18720E963604B70

PS C:\Users\Administrator.CORP> $cert = Get-TrustAuthorityKeyProviderServerCertificate -KeyProviderServer $kp.KeyProviderServers
PS C:\Users\Administrator.CORP> Add-TrustAuthorityKeyProviderServerCertificate -ServerCertificate $cert

Certificate                              Trusted    KeyProviderServerId       KeyProviderId
-----------                              -------    -------------------       -------------
[Subject]...                             True                                 domain-c8-clkp

PS C:\Users\Administrator.CORP> $kp = Get-TrustAuthorityKeyProvider -TrustAuthorityCluster $vTA
PS C:\Users\Administrator.CORP> $kp.Status

KeyProviderId Health HealthDetails ServerStatus
------------- ------ ------------- ------------
domain-c8-kp4     Ok {}            {192.168.210.22}

What to do next

Continue with Export the Trust Authority Cluster Information.