Use Custom SSL Certificates for VirtServer
VirtServer works through the HTTPS protocol. To secure the traffic, VirtServer uses a CA certificate located in the <VirtServer>/bin/.virtserverkeystore file.
You may want to replace the default certificate with your own certificate. This can be either a trusted certificate or a self-signed certificate that you generate for your purposes for free.
Note
You use this certificate only to secure traffic to and from the VirtServer web interface. To configure SSL for virtual services, use the virtSSL settings in the virt-server.yml file.
Install a custom certificate
The steps below explain how to create and install a certificate for your VirtServer. If you already have a certificate for your VirtServer computer (server), your actions may differ a little from the described procedure.
In our explanations, we use the keytool command-line utility. It is part of Java packages and resides in the <Java>/bin directory. For complete information on its command-line arguments, see Keytool documentation.
Basic concepts
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
VirtServer gets certificates from keystores of the JKS format. The path to them is specified by the VirtServer settings file (virt-server.yml):
... server: applicationConnectors: # For security reasons, we allow communication only over https - type: https port: 9090 keyStorePath: .virtserverkeystore keyStorePassword: '!serverSecret!' validateCerts: false trustStorePath: .cacerts ...
The setting points to the keystore file that contains the pre-installed VirtServer certificate. The file resides in the <VirtServer>/bin folder and its name is .virtserverkeystore.
The other setting, , points to the keystore file that contains trusted root certificates, that is, the certificates signed by certification authorities (CA). Browsers use these certificates for verifying the certificate chain. If you have your own VirtServer keystore with such certificates on the computer, you can specify its path in the setting.
Custom certificate configuration
Add your certificate stores or files to the .readyapi/virtserver directory.
Tip
Always store custom certificates in .readyapi/virtserver to keep them safe during upgrades.
To use a custom truststore or keystore, perform the following steps:
Open the relevant configuration YAML file (for example,
virtserver.yml).Specify the keystore and truststore file names located in
.readyapi/virtserver.
Example:
keyStorePath: myCustomKeystore.jks keyStorePassword: ******** trustStorePath: myCustomTruststore.jks
1. Create a certificate for your VirtServer computer
We start with creating a self-signed certificate for VirtServer:
Run the following command. It creates a private and public key pair. Wrap the public key into a certificate and store all this data in 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.Important
It is important to specify
-keyalgas RSA.-alias my-virtserveris the alias of your certificate in the keystore. You can enter any string. We selected my-virtserver as an example.-keystoreis the file name and path of the keystore to be created, for example,path/keystore.jksc:/certificates/my-keystore.jks.
Upon running the command, the
keytoolutility asks 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 that 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 send the created certificate to a certificate authority for signing, and they may need to check this data.
At the end, the utility asks if the entered data is correct and asks you to specify the key password.
2. Create a certificate request
After you create the keystore, you need to create a certificate request. Use a command line like the one below:
keytool -certreq -alias my-virtserver -file path/cert-request-file-name.crt -keystore path/my-keystore.jks -ext san=dns:virtserver-computer-name,dns:alternative-computer-name,ip:192.168.10.205
keytool asks you to enter the keystore password. Enter the password you used to create the keystore.
About parameters:
-keystoreand-aliasare 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.Important
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, do not accept the resulting certificate.Type in the name that you entered in a browser to access the VirtServer Web Interface. For example, if you use the URL
https://my-server:9090/virtserver, specifymy-serveras the name:-ext san=dns:my-serverIt is a good practice to register both the computer name and the computer name and domain:
-ext san=dns:my-server,dns:my-server.domainIf you are going to use the IP address in the URL, set it in the
sanparameter as well:-ext san=dns:my-server,dns:my-server.domain,ip:192.168.10.205The
dns:andip:prefixes are obligatory; they indicate the name type.
3. Send the certificate request to a CA
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).
The certificate authority answers you with a file containing the signed certificate (it is also called a certificate reply or a CA-signed certificate). You need to import this file to your keystore.
Notes:
You need the CA-signed certificate for VirtServer as well as all the intermediate and root certificates.
We import the certificate reply into your keystore with the
keytoolutility. 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.Important
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) do not accept the certificate.
4. Import the CA-signed certificate
Import the CA-signed certificates to your keystore. Use a command line like this one:
keytool -importcert -file path/ca-signed-certificate-file.crt -alias some-cert-alias -keystore path/my-keystore.jks
Notes:
Import certificates into 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.
Important
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.
5. Configure VirtServer to use your keystore
Copy your keystore file to the
<VirtServer>/binfolder.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' certAlias: my-virtserver validateCerts: false trustStorePath: .cacerts ...
Start VirtServer and try to open its Web Interface in the browser.
6. Install the root certificate on user computers
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's 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:
Copy the root certificate file to the user machines, from which you can access VirtServer.
On these machines, start the browser you 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.
Important
If you do not install the root certificate on user machines, you receive a warning about a non-secure connection.
SNI and DropWizard
We have upgraded the DropWizard library with our latest release VirtServer 3.20.0, which also includes a Jetty upgrade.
However, Jetty 10.0.x introduces stricter SNI host checking; hence, after the update, you may encounter issues while making requests over HTTPS. Find more details regarding this issue here.
To solve this issue, the HttpsConnectorFactory has a disableSniHostCheck configuration option, which enables or disables stricter security for an application. By default, in VirtServer, this is set to true, and the SNI host check is disabled or turned off.
If you want to change this setting, follow these instructions:
Create a signed keystore with the certs you wish VirtServer to be accessible through. An example can be found here: SSL with CA signed certificate from Let's Encrypt with a domain registered at GoDaddy.
Change connector (fields “VirtServerapplicationConnector” or “adminConnector”) for connecting to . Add the field 'disableSniHostCheck' to the connector, and set it to 'false'. Change 'keyStorePath' to point to your keystore. Change 'keyStorePassword' to the password needed to unlock the Keystore.
Restart VirtServer.