Checking vCenter Server certificate requirements with PowerShell

Given the number and the complexity of certificate-related issues, I wanted an automated way to check whether a certificate file meets the vCenter Server certificate requirements.

There are 2 ways to extract the necessary information from a certificate file : openssl.exe and the cmdlet Get-PfxCertificate, which was introduced with PowerShell 3.0.

Here is the openSSL command and its output :

OpenSSL command
 
Here is the Get-PfxCertificate command and its output :

Get-PfxCertificate
 

I wrote a PowerShell function named Test-VpxdCertificate, which checks if a certificate file (.crt or .cer) meets all the requirements. I chose to build this tool upon the Get-PfxCertificate cmdlet for 2 main reasons :

  • openssl.exe returns plain text and you know what I think about text-parsing in PowerShell.
  •  

  • You don’t really need to have PowerShell 3.0 on the vCenter Server itself.
    You can copy the certificate file to another machine (which has PowerShell 3.0 or later) and run the cmdlet from there.
    Given the huge boost in functionality in 3.0 compared with 2.0 and the fact that 3.0 can be installed on down-level OSes, if you still don’t have any machine with 3.0 or later, you probably don’t need, or want, or deserve PowerShell automation.

What does it check ?

 
The vCenter Server certificate requirements are not clearly and exhaustively documented. There is something in the vSphere 5.0 documentation, but this is old and not exhaustive.
Fortunately, we can deduce most of the requirements from the KB article explaining how to create certificate requests for custom certificates.

So here are the certificate requirements for vCenter Server 5.x :

  • Certificate must be X.509 v3.
  • Certificate should begin with : “—–BEGIN CERTIFICATE—–“.
  • Certificate should end with : “—–END CERTIFICATE—–“.
  • The subject Alternative Name must contain the FQDN of the vCenter server.
  • The certificate must be valid : the current date must be between the “Valid from” date and the “Valid to” date.
  • The Key usage must contain the following usages : Digital Signature, Key Encipherment, Data Encipherment
  • The Enhanced key usage must contain : “Server Authentication” and “Client Authentication”.
  • The public key algorithm must be : RSA (2048 Bits).
  • The certificate must NOT be a wildcard certificate.
  • The signature hash algorithm must be SHA256, SHA384, or SHA512.

And here are the requirements for vCenter Server 6.0 :

  • Certificate must be X.509 v3.
  • Certificate should begin with : “—–BEGIN CERTIFICATE—–“.
  • Certificate should end with : “—–END CERTIFICATE—–“.
  • The subject Alternative Name must contain the FQDN of the vCenter server.
  • The certificate must be valid : the current date must be between the “Valid from” date and the “Valid to” date.
  • The Key usage must contain the following usages : Digital Signature, Key Encipherment.
  • The public key algorithm must be : RSA (2048 Bits).
  • The certificate must NOT be a wildcard certificate.
  • The signature hash algorithm must be SHA256, SHA384, or SHA512.

How to use it :

 
CertFilePath2
 
Here, we specified the certificate file path and the vCenter FQDN because this was not run from the vCenter Server itself.
If we run this command from the vCenter Server and if it is able to resolve its own FQDN, then there is no need to use the -vCenterFQDN parameter.
If we run this command from the vCenter Server and if the certificate is at its default location, then there is no need to use the -CertFilePath parameter.

The function performs a test for each of the requirements listed above and outputs an object with a property corresponding to each of these tests. The value of each property is either True or False. True means that the certificate passed the corresponding test and False means that it failed the test.

As we have seen above, the vCenter Server certificate requirements are different between vCenter 5.x and 6.0.
So, the -VpxdVersion parameter is used to specify the version of vCenter Server and the value of this parameter determines which tests are performed.
If the function is run from the vCenter Server itself, it will detect the vCenter version by itself and use this value, unless it is specified via the -VpxdVersion parameter.

By the way, the parameters -CertFilePath, -vCenterServerFQDN and -VpxdVersion are positional, so we can save some typing, like so :

PS C:\> Test-VpxdCertificate "$env:USERPROFILE\Desktop\rui.crt" "VC1.vcloud.local" "5.x"


Certificate ends with "-----END CERTIFICATE-----"             : True
Signature hash algorithm is SHA256 or higher                  : True
Certificate is NOT a wildcard certificate                     : True
Current date is between the "Valid from" and "Valid to" dates : True
Certificate has the required key usages                       : True
Certificate begins with "-----BEGIN CERTIFICATE-----"         : True
Certificate has the required enhanced key usages              : False
Subject alternative names contain the vCenter FQDN            : True
Public key algorithm is RSA 2048 or higher                    : True
Certificate is X.509 v3                                       : True

 
Here, we see that the vCenter certificate doesn’t meet the requirement regarding the enhanced key usages. To have better insight into why a certificate failed a test, we can use the -Verbose parameter. This allows us to see the certificate properties which are checked and their values :

Verbose2
 
Now, we can see why it failed the test for enhanced key usage : it is missing the “Client Authentication” enhanced key usage.

But there is no requirement for enhanced key usage in vCenter 6.0, so this certificate passes all the checks for 6.0 :

vpxd60
 
On the other side of the verbosity spectrum, we can just output a boolean value : True or False using the -Quiet parameter. True means that the specified certificate meets all the requirements, False means that it doesn’t meet all the requirements :

Quiet2
 
This behaviour is conform to the -Quiet parameter of Test-Connection and other Test-* cmdlets. This is useful mostly when we call the cmdlet from another automation tool and we do something, depending on the result (True or False).

As usual, I packaged the function in a nice little module, which is available here.

Leave a Reply

Your email address will not be published. Required fields are marked *