This article describes how to generate files that will be sent to the Trusted Certificate Authority (CA) to obtain valid SSL certificate for VDI-in-a-Box appliance. The steps defined in this article apply to VDI-in-a-Box 5.0, 5.1, and 5.2.

Note: In version 5.3, VDI-in-a-Box introduced a web-based interface to manage SSL certificates. More information on this UI can be found in VDI-in-a-Box section of edocs under Manage SSL Certificates.

Requirements

• VDI-in-a-Box 5.0 or newer server

• SSH utility like PuTTY or SecureCRT

• SFTP utility like WinSCP, scp or FileZilla

Background

The VDI-in-a-Box appliance ships with a self-signed SSL Certificate that is not trusted by Web browsers and devices. The experience varies by Web browser but the best user experience can be accomplished by installing a valid and trusted SSL Certificate. Along with a better user experience, a trusted SSL Certificate can also overcome some connectivity issues with the Citrix Receiver in certain types of environments.

---

Instructions

Using Scripts to Create Certificate Request and Import the Certificates using VDI-in-a-Box 5.2 and Earlier

Note: For ease, the script to generate Certificate Request and to import the certificates are available in the same zip file.

1. Download and unzip the attached file.

2. Use the SFTP utility (such as FileZilla) to copy the two script files to /home/kvm/kvm directory on the VDI-in-a-Box appliance.

3. Execute the following two commands from /home/kvm/kvm folder:
   The command cd /home/kvm/kvm ensures that you are in the right place to perform the following steps:

   chmod 777 sslcertrequest.sh
   ​chmod 777 sslcertimport.sh

4. Run the scripts using the following syntax:
   sh sslcertrequest.sh
   This action creates a certificate request file certreq.csr and stores it under /home/kvm/kvm/vdimgrkeystore folder. You can give this certreq.csr file to your CA to get the certificates in the .crt format.

5. Save the .crt file to /home/kvm/kvm/vdimrkeystore and then run the second script:
   sh sslcertimport.sh
   This action imports the certificates into the keystore. Ensure to take a backup of your current keystore and then replace it with the new keystore with all your certificates. At the end of the script, Tomcat will be restarted and you can test the Web site using the same FQDN for which you generated the script without any certificate related errors.
   Note: Having two keystorePassword lines in the server.xml file might cause Tomcat to fail when starting. Ensure there is only one instance of the keystorePassword. As for ViaB 5.2 or later, you must remove an extra line after running the sslcertimport.sh.
   For example, you must delete “line 69” in the following server.xml. 

   <Sample server.xml> ---------- 66 <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true" 67 ciphers="SSL_RSA_WITH_RC4_128_MD5, SSL_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA" 68 keystoreFile="conf/.keystore" keystorePass="citrix" 69 keystorePass="changeit" 70 maxThreads="150" scheme="https" secure="true" 71 clientAuth="false" sslProtocol="TLS" URIEncoding="UTF-8"/> ----------

Manual Procedure

SSH into the VDI-in-a-Box Virtual Appliance

Windows users might use utilities such as PuTTY or SecureCRT to SSH into the console. Macintosh and Linux users can use the built-in Terminal application to start SSH sessions.

1. Open the SSH application or Terminal instance.

2. Connect to the VDI-in-a-Box appliance using the DNS name or IP address. Use the default credentials:
   kvm / kaviza123

   

Generating the Keystore, Key Pair, and CSR

This section covers the steps required to generate the files that will be sent to the Trusted CA. These files will be created using the Java keytool. Refer to keytool - Key and Certificate Management Tool for more information about this utility.

Keystore Directory

1. Use the mkdir utility to create a keystore directory in /home/kvm:
   mkdir /home/kvm/kvm/keystore

2. Use the cd utility to change to the keystore directory:
   cd /home/kvm/kvm/keystore

   

Generating Java Keystore and Key Pair 

1. Use the keytool utility to generate a private key on the VDI-in-a-Box virtual appliance. Replace hostname in the alias command with your VDI-in-a-Box server hostname:
   keytool –genkey –alias hostname –keyalg RSA –keysize 2048 –keystore kmgr.keystore

2. Select a password and confirm the same (must be at least 6 characters).

3. Fill the required fields and click Enter after each line. When prompted to confirm the information, type Yes and then click Enter.
   Note: The first item, “What is your first and last name?” is equivalent to the Common Name (CN) field in other key generation tools. This must be in the form of a valid hostname (such as vdi.company.com); otherwise, the Trusted CA rejects the Certificate Signing Request (CSR).

4. Click Enter to use the same password set in Step 2.

   

Generating the CSR

1. Run the keytool utility again to create a CSR. This file will be saved to the current directory (/home/kvm/kvm/keystore) and will be sent to the Trusted CA. Replace hostname in the alias option with your VDI-in-a-Box server hostname:
   keytool –certreq –alias hostname –file kmgr.csr –keystore kmgr.keystore

2. Type the keystore password set in the preceding section.

3. Use the ls utility to verify both kmgr.csr and kmgr.keystore files exist.

   

Copying the CSR to Local Computer

1. Download and install your favorite SFTP utility, such as WinSCP or FileZilla.
   There are many free utilities available and FileZilla is used in this example.

2. Connect using the SFTP protocol to the VDI-in-a-Box virtual appliance IP address or hostname.

3. Use the credentials: kvm / kaviza123

4. Browse to the /home/kvm/kvm/keystore directory on the VDI-in-a-Box server and transfer or copy the file to your local computer.

   

Requesting an SSL Certificate from a Trusted CA

A valid SSL Certificate can be obtained from most Trusted CA. Each CA and certificate will have a different chain; most of them will include intermediate certificates in order to complete the chain. The list of CAs include, but is not limited to GoDaddy, GeoTrust, VeriSign, Thawte, and DigiCert.

The SSL Certificate instructions are different for each CA. Refer to the CA documentation on how to upload a CSR and download an SSL Certificate. Most CAs allow customers to either upload the CSR file or paste the contents of the CSR file into an upload window.

The following screen shot shows how a kmgr.csr file looks like in a text editor:

The above mentioned sample code is provided to you as is with no representations, warranties or conditions of any kind. You may use, modify and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the sample code may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the sample code fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the sample code. In no event should the code be used to support ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SAMPLE CODE, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Although the copyright in the code belongs to Citrix, any distribution of the sample code should include only your own standard copyright attribution, and not that of Citrix. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the sample code.

This article describes how to generate files that will be sent to the Trusted Certificate Authority (CA) to obtain valid SSL certificate for VDI-in-a-Box appliance

CTX132234 - How to Install SSL Certificate onto the VDI-in-a-Box Virtual Appliance