Use Custom SSL Certificates for VirtServer

About certificates

Security certificates help browsers ensure that you have connected to the web server whose address you entered in the Address bar.

Every certificate contains the web server name, for which this certificate was issued. Also, it contains information on the certificate authority (CA) that signed the certificate and confirms the web server identity.

You can find information on certificates in your web browser:

In the image above, the root certificate certifies the intermediate certificate, which, in turn, signs the SmartBear web site certificate.

A web browser needs to verify all the certificates in the chain to ensure the connection is secure.

Where VirtServer stores certificates

We will start with creating a self-signed certificate for VirtServer:

1. Run the following command. It will create a private and public key pair. Wrap the public key into a certificate and store all these data to a keystore:

   keytool -genkeypair -keyalg RSA -alias my-virtserver -keystore path/my-keystore.jks

   A few words about parameters and their values:

   • -keyalg RSA - Specifies the encryption algorithm.

     It is important to specify -keyalg as RSA.

   • -alias my-virtserver is the alias of your certificate in the keystore. You can enter any string. We selected my-virtserver as an example.

   • -keystore path/keystore.jks is the file name and path of the keystore to be created, for example, c:/certificates/my-keystore.jks.

2. Upon running the command, the keytool utility will ask you several questions:

   • Enter keystore password - Specify a password for the keystore to be created.

   • What is your first and last name? - It is supposed you enter a subject name here, that is, the name of the certified computer. You can enter either the name of your VirtServer machine, or a string like My VirtServer instance.

   • Answer the other questions like What is the name of your organization unit?, What is the name of your organization? and the questions about your address. We will send the created certificate to a certificate authority for signing, and they may need to check this data.

   • At the end, the utility will ask if the entered data is correct and will ask you to specify the key password.

After you create the keystore, you will need to create a certificate request. Use a command line like the one below:

keytool will ask you to enter the keystore password. Enter the password you used to create the keystore.

About parameters:

• -keystore and -alias are the keystore and the alias you created at step 1.

• -ext san=dns:{name},ip:{address} - The name or IP address of your VirtServer computer.

  It is important to use the -ext san=... argument in the command line. This argument specifies the name and IP address of the certified VirtServer. Without these data, modern browsers, like Chrome, will not accept the resulting certificate.

  Type in the name you will enter in a browser to access the VirtServer Web Interface. For example, if you use the URL https://my-server:9090/virtserver, specify my-server as the name:

  -ext san=dns:my-server

  It is a good practice to register both the computer name and the computer name and domain:

  -ext san=dns:my-server,dns:my-server.domain

  If you are going to use the IP address in the URL, set it in the san parameter as well:

  -ext san=dns:my-server,dns:my-server.domain,ip:192.168.10.205

  The dns: and ip: prefixes are obligatory, they indicate the name type.

1. After you create a certificate request file, contact a certificate authority (CA) and send your certificate request to them.

   The CA can be a publicly available authority like GeoTrust, VeriSign, DigiCert or Comodo, or it can be your system administrator – many companies use security certificates that are valid within their local network only. Typically, system administrators create these certificates with tools like XCA, Protecle or some other. (Both tools are third-party applications that are not supported by SmartBear).

2. The certificate authority will answer you with a file containing the signed certificate (it is also called a certificate reply or a CA-signed certificate). You will need to import this file to your keystore.

Notes:

• You will need the CA-signed certificate for VirtServer as well as all the intermediate and root certificates.

• We will import the certificate reply into your keystore with the keytool utility. This utility supports X.509 certificates as well as certificate chains in the PKCS#7 format. Ask your certificate authority to provide certificates in these formats. For simplicity, we suggest that you receive the CA-signed certificate for the VirtServer computer and intermediate certificates in separate files.

• It is important that all the certificates be signed with SHA256 or some other secure algorithm. The SHA1 algorithm is not considered secure enough. If the VirtServer certificate or some other certificate in the chain is signed with SHA1, modern browsers (like recent versions of Chrome) will not accept the certificate.

Import the CA-signed certificates to your keystore. Use a command line like this one:

Notes:

• Import certificates to the keystore you created at step 1.

• Start the import with the root certificate and continue with intermediate certificates. Import the CA-signed VirtServer certificate last.

• For the VirtServer certificate, use the alias you used for creating the certificate and certificate request (in our example, it is my-virtserver). For the root and intermediate certificates, use any aliases you want.

1. Copy your keystore file to the <VirtServer>/bin folder.

2. Open the VirtServer settings file (virt-server.yml) in any text editor and change it in the following way:

   ...
   server:
     applicationConnectors:
     # For security reasons, we allow communication only over https
     - type: https
       port: 9090
       keyStorePath: .virtserverkeystore my-keystore.jks
       keyStorePassword: '!serverSecret!' 'my-keystore-password'
       keyManagerPassword: '!managerSecret!' 'my-keymanager-password'
       certAlias: my-virtserver
       validateCerts: false
       trustStorePath: .cacerts
   ...

3. Start VirtServer and try to open its Web Interface in the browser.

In order for the new certificate to work successfully, the browser should be able to validate the whole certificate chain. This means the root certificate should be in the list of Trusted Certification Authorities of the browser on a user computer.

If your VirtServer certificate was signed by some publicly available certificate authority, most likely, you already have the appropriate root certificate in this list. However, if the VirtServer certificate was signed by your local CA (like a system administrator), you need to add the root certificate to the list of Trusted Certification Authorities in your browser:

1. Copy the root certificate file to the user machines, from which you will access VirtServer.

2. On these machines, start the browser you will use, open the browser settings dialog and add the root certificate to the list of Trusted Certification Authorities. For more information on the steps to perform, see your browser documentation.

   Note:

   You may need to restart your browser after changing the list.

If you do not install the root certificate on user machines, you will receive a warning about a non-secure connection.