Citrix Hypervisor

Certificate verification

When certificate verification is enabled for a pool, all TLS communication endpoints on its management network use certificates to validate the identity of their peers before transmitting confidential information.

Behavior

Connections initiated by a Citrix Hypervisor server on the management network require that the destination endpoint provides a TLS certificate to verify its identity. This requirement affects the following items that are part of the pool or interact with the pool:

  • servers in the pool
  • Citrix Hypervisor Center
  • third-party clients that use the API

Certificate verification is compatible with both the self-signed certificates provided by Citrix Hypervisor and user-installed certificates signed by a trusted authority. For more information, see Install a TLS certificate on your server.

Each Citrix Hypervisor server in a pool has two certificates that identify it:

  • Pool-internal identity certificates are used to secure communications between servers within the pool. For communication within the pool, Citrix Hypervisor always uses self-signed certificates.

  • Server identity certificates are used to verify the identity of a server to any client applications that communicate with the pool on the management network. For communication between the server and a client application, you can use self-signed certificates or you can install your own TLS certificates on your servers.

When a server first joins the pool or a client first makes a connection to the pool, the pool trusts the connection. During this first connection, certificates are exchanged between the pool and the joining server or the connecting client. For all subsequent communications by this server or client on the management network, the certificates are used to verify the identity of the parties involved in the communication.

If a Citrix Hypervisor server that has certificate verification enabled attempts to join a pool that does not have this feature enabled, the operation is not successful. Citrix Hypervisor Center provides a warning message that advises you to enable certificate verification on the pool.

If a Citrix Hypervisor server that does not have certificate verification enabled attempts to join a pool that does have this feature enabled, the operation is not successful. Citrix Hypervisor Center provides a warning message that advises you to enable certificate verification on the joining server.

When a server leaves a pool with certificate verification enabled, both the server and the pool delete the certificates that relate to the other.

Virtual appliance behavior

During this preview, the Citrix Hypervisor Conversion Manager virtual appliance is exempt from the certification checking requirement when it acts as a TLS client end point.

During this preview, the Workload Balancing virtual appliance can be used with certificate verification. You must ensure that the following conditions are met:

  • The key length of the self-signed certificate is 2048
  • A necessary parameter is added to the stunnel configuration
  • The Workload Balancing self-signed certificates are installed into your Citrix Hypervisor server

For more information, see Configure Citrix Hypervisor to verify the self-signed certificate.

Enabling certificate verification for your pool

Certificate verification is enabled by default on fresh installations of Citrix Hypervisor 8 Cloud and later.

If you upgrade from an earlier version of Citrix Hypervisor, certificate verification is not enabled automatically and you must enable it. Citrix Hypervisor Center prompts you to enable certificate verification the next time you connect to the upgraded pool.

Before enabling certificate verification on a pool, ensure that no operations are running in the pool.

Enable by using Citrix Hypervisor Center

Citrix Hypervisor Center provides several ways to enable certificate verification.

  • When first connecting the Citrix Hypervisor Center to a pool without certificate verification enabled, you are prompted to enable it. Click Yes, Enable certificate verification.

  • In the Pool menu, select Enable Certificate Verification.

  • On the General tab of the pool, right-click the entry Certificate Verification and choose Enable Certificate Verification from the menu.

Enable by using the xe CLI

To enable certificate verification for a pool, run the following command in the console of a server in the pool:

xe pool-enable-tls-verification

Managing certificates

You can install, view information about, and reset the certificates that are used to verify the identity of a server.

Installing certificates

You can install your own TLS certificate for the server to present as its identity certificate when receiving connections from client applications on the management network.

For more information, see the Install a TLS certificate on your server

Viewing certificate information

To find out whether a pool has certificate verification enabled:

  • In Citrix Hypervisor Center, look in the General tab for the pool. The General section has an entry for Certificate Verification which shows whether certificate verification is enabled or disabled. This tab also contains a Certificates section that lists the name, validity, and thumbprint for the CA certificates.

  • With the xe CLI, you can run the following command:

     xe pool-param-get uuid=<pool_uuid> param-name=tls-verification-enabled
    

    If certificate verification is enabled, the line tls-verification-enabled ( RO): true appears in the command output.

To view information about the certificates on a Citrix Hypervisor server:

  • In Citrix Hypervisor Center, go to the General tab for that server. The Certificates section shows the thumbprint and the validity dates for the server identity certificate and the pool-internal identity certificate.

  • With the xe CLI, you can run the following command:

     xe certificate-list
    

Refreshing pool-internal identity certificates

You can refresh the pool-internal identity certificate by using the xe CLI:

  1. Find the UUID of the server whose certificate you want to reset by running the following command:

    xs host-list
    
  2. To reset the certificate, run the following command:

    xe host-refresh-server-certificate host=<host_uuid>
    

    Note

    Any host selector parameter can be used with this command to indicate the server to reset the certificate on.

Resetting server identity certificates

You can reset the server identity certificate from the Citrix Hypervisor Center or from the xe CLI. Resetting a certificate deletes the certificate from the server and installs a new self-signed certificate in its place.

To reset a certificate in Citrix Hypervisor Center:

  1. Go to the General tab for the server.
  2. In the Certificates section, right-click on the certificate you want to reset.
  3. From the menu, select Reset Certificate.
  4. In the dialog the appears, click Yes to confirm the certificate reset.

Alternatively, in the Server menu, you can go to Certificates > Reset Certificate.

When you reset a certificate, any existing connections to the server are disconnected — including the connection between Citrix Hypervisor Center and the server.

To reset a certificate by using the xe CLI:

  1. Find the UUID of the server whose certificate you want to reset by running the following command:

    xs host-list
    
  2. To reset the certificate, run the following command:

    xe host-reset-server-certificate host=<host_uuid>
    

    Note

    Any host selector parameter can be used with this command to indicate the server to reset the certificate on.

When you reset a certificate, any existing connections to the server are disconnected — including the connection between Citrix Hypervisor Center and the server. Citrix Hypervisor Center reconnects automatically to the server after a certificate reset.

Expiry alerts

Citrix Hypervisor shows alerts in the Notifications view when your server identity certificates, pool-internal identity certificates, or pool CA certificates are close to their expiry date.

Temporarily disabling certificate verification

We do not recommend that you disable certificate verification after it has been enabled on a server or pool. However, Citrix Hypervisor provides commands that can be used to disable certificate verification on a per-server basis when troubleshooting problems with certificates.

To temporarily disable certificate verification, run the following command on the server console:

xe host-emergency-disable-tls-verification

Citrix Hypervisor Center shows an alert in the Notifications when certificate verification is disabled on a server in a pool where the feature is enabled.

After you have resolved any issues with certificates on the server, ensure that you reenable certificate verification on it. To reenable certificate verification, run the following command on the server console:

xe host-emergency-reenable-tls-verification
Certificate verification