Applies to ReadyAPI 3.2.7, last modified on May 28, 2020

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 will 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.

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:

Service virtualization and API testing: Security certificates

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 keyStorePath 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, trustStorePath, 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 keystore with such certificates on the VirtServer computer, you can specify its path in the trustStorePath setting.

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 -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 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:

keytool -importcert -file path/ca-signed-certificate-file.crt -alias some-cert-alias -keystore path/my-keystore.jks

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'
        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.

See Also

VirtServer Settings
Configuring and Using VirtServer

Highlight search results