StorNext GUI: Installing a SSL Certificate from a Certificate Authority







Introduction to SSL


SSL, or Secure Socket Layer, is a technology which allows web browsers and web servers to communicate over a secured connection. This means that the data being sent is encrypted by one side, transmitted, then decrypted by the other side before processing. This is a two-way process, meaning that both the server AND the browser encrypt all traffic before sending out data.


Another important aspect of the SSL protocol is Authentication. This means that during your initial attempt to communicate with a web server over a secure connection, that server will present your web browser with a set of credentials, in the form of a "Certificate", as proof the site is who and what it claims to be. In certain cases, the server may also request a Certificate from your web browser, asking for proof that you are who you claim to be. This is known as "Client Authentication," although in practice this is used more for business-to-business (B2B) transactions than with individual users. Most SSL-enabled web servers do not request Client Authentication.








Certificates


In order to implement SSL, a web server must have an associated Certificate for each external interface (IP address) that accepts secure connections. The theory behind this design is that a server should provide some kind of reasonable assurance that its owner is who you think it is, particularly before receiving any sensitive information. While a broader explanation of Certificates is beyond the scope of this document, think of a Certificate as a "digital driver's license" for an Internet address. It states what company the site is associated with, along with some basic contact information about the site owner or administrator.


This "driver's license" is cryptographically signed by its owner, and is therefore extremely difficult for anyone else to forge. A Certificate is typically purchased from a well-known Certificate Authority (CA). Such certificates can be electronically verified -- in effect, the Certificate Authority will vouch for the authenticity of the certificates that it grants, so you can believe that that Certificate is valid if you trust the Certificate Authority that granted it.


In many cases, however, authentication is not really a concern. An administrator may simply want to ensure that the data being transmitted and received by the server is private and cannot be snooped by anyone who may be eavesdropping on the connection. Fortunately, Java provides a relatively simple command-line tool, called keytool, which can easily create a "self-signed" Certificate. Self-signed Certificates are simply user generated Certificates which have not been officially registered with any well-known CA, and are therefore not really guaranteed to be authentic at all. Again, this may or may not even be important, depending on your needs.






Configuration

The password and the alias that the GUI uses are the 
Default tomcat values. 
password: changeit
alias: tomcat
Note: A custom password can be specified if you like. You will also need to specify the custom
 password in the server.xml configuration file, as described later.
 
# /usr/adic/java/jre/conf/bin/keytool -storepasswd -keystore
/usr/adic/gui/config/.keystore
Enter keystore password:  changeit
New keystore password:  new-password
Re-enter new keystore password:  new-password
Installing a Certificate from a Certificate Authority 
In order to obtain a Certificate from the Certificate Authority of your choice you have to create a so called
 Certificate Signing Request (CSR). That CSR will be used by the Certificate Authority to create a 
Certificate that will identify your website as "secure". To create a CSR follow these steps:
Create a local self-signed Certificate
# keytool -genkey -keystore /usr/adic/gui/config/.keystore -alias
<certificateAlias> -keyalg RSA -keysize 2048
Note: You will be prompted for general information about this Certificate, such as company, 
contact name, and so on. This information will be displayed to users who attempt to access a 
secure page in your application, so make sure that the information provided here matches what they will expect.
The CSR is then created with
# /usr/adic/java/jre/bin/keytool -certreq -keystore
/usr/adic/gui/config/.keystore -alias <certificateAlias> -file certreq.csr
Now you have a file called certreq.csr that you can submit to the Certificate Authority (look at the documentation of the Certificate Authority website on how to do this). 
Make sure that you request a Tomcat or Java-compatible format. In return you get a Certificate.
Importing the Certificate
Now that you have your Certificate you can import it into your local keystore. We recommend that you 
make a copy of the keystore first. 
If there are any intermediate certificates provided, which are not in the keystore, you will need to import
 them into the keystore before you import the certificate file. 
You can import the intermediate certificates in the same way as the Root certificate. 
Note: When important an intermediate certificate, use an alias that does not already exist. 
When importing the CSR Certificate, you MUST use the same alias that you used to generate the CSR.
# keytool -importcert -keystore /usr/adic/gui/config/.keystore -alias
<certificateAlias> -file <responseFile> -trustcacerts
Note: If you get a warning that you need to delete the existing alias first, then there is a problem with 
the certificate, and it is not a proper response to the
existing certificate. Otherwise, it should indicate a successful import. 
For verification run the following command and verify in particular, that the type for the CSR file is 
privateKeyEntry, not trustedCertEntry. 
The intermediate certificates should have a type of trustedCertEntry.
keytool -list -v -keystore /usr/adic/gui/config/.keystore
At this point we have to update tomcat server configuration:
/usr/adic/tomcat/conf/server.xml
Modify these 2 values accordingly to your configuration
      keystorePass="changeit"
      keyAlias="tomcat"
Tomcat only reads the keystore file on startup, so you can carry out operations on the file without 
affecting the running application. 
Changes to the certificate store do not take effect until Tomcat is restarted.
# /etc/init.d/stornext_web restart
It may be necessary to delete the default tomcat alias 
#  keytool -delete -alias tomcat -keystore /usr/adic/gui/config/.keystore
# /etc/init.d/stornext_web restart

 

Audience: 
Public Unrestricted
Review/Evaluate: 
2016-04-20
Document Type: