Internet Security, Certificates, SSL

_

_

Introduction to Preparing Your Operational Environment

Before you configure your opentaps system with any of your business data, or your company's confidential information, or your company employee's data, it will be prudent to consider the security of your opentaps system servers and the related internet network security. Best practices with respect to this topic suggest the following partial list of salient points:

• Your server should be protected by a properly configured firewall to allow only the required forms of network access, as defined by your management and their technical system administrative staff.
• Any internet access to the opentaps server should probably be limited to SSL (secure socket layer) internet transmission layer security, as determined by your management and their technical system administrative staff. Consider both the public internet and any in-house local internets in this topic.
• You should secure all of the opentaps IDs that are active on the system, using a strong and unique password having properly limited distribution to users with a business need for them, and you should disable all other IDs on opentaps.
• You should make sure that your technical system administrator has secured all of the opentaps host server software components and related ports of every kind, so that no unintended routes of access are possible on your system.
• You should make sure that your opentaps server has physical security that is practiced 100% of the time, and that is robust enough to meet your management's requirements.
• Before you put any of your opentaps system functions into a production mode of operation, you should develop, test, and deploy your methods for system data backup and for system data restoration. You should actually practice the system data restoration periodically to make sure that it actually does work.
• Consider whether you will need a server for testing data restoration, migration, or new software component releases that is separate from the production servers that you use. (Usually, production servers are off limits for testing purposes.)
• Included in this preparation, you should include a determination of when backup will be collected, by whom, and where it will be stored so that if your operational facility is breached or destroyed there will still be a copy of your system backup data available, somewhere else.
• Make your own list adding all items to this topic which your company deems essential to your own best practices, and complete working your list. When making your own complete list, you may wish to consider what you would do if the internet access suffers an outage, either on the public internet or on your own local internets, or if the physical opentaps server computer suffers an outage.

If you do not need to attach your server to the internets while you are doing preliminary configuration, and preparing your environment then you may be able to phase some of the steps to make progress while other steps are still being completed.

Using SSL for opentaps Internet Security

opentaps can be configured to permit access only by the secure internet protocols, thus reducing the opportunity for unauthorized access to your system. This means having your users log-in and use your opentaps system via the secure internet https protocol (rather than non-encrypted http), and using the SSL-enabled ports (default on opentaps is port 8443) rather than the non-encrypted ports such as 80 or 8080.

Then there is the question of what to do about the SSL Certificate. The certificate is simply your internet identification "papers", including an encryption key that is uniquely yours, and these items are kept in a unique secure, encrypted file which acts as a lock box. This certificate (identity document) can be one that you have created and signed yourself, or it can be one that you initiate and submit to a public "certificate authority" recognized by the industry at large. Such a certificate authority will validate your identity first, then sign your certificate and return it to you for installation on your server(s). Thus, a chain of trust is created that your end-users or the customers of your eCommerce operations can rely upon.

Caution and Warning about Security and Access

When opentaps is downloaded in the release package and installed it contains a certificate for one of the organizations which produce the opentaps system releases. So that certificate is not yours, and it is not unique since many people will download the release code and install it with that common certificate. While you could operate with this default certificate for non-critical testing (using no private information of any kind) you must install your own unique certificate for secure use of the opentaps system. Also, the opentaps system, when it is initially installed, has several user identities enabled with trivial passwords that everyone knows about. You should disable or change passwords on all the existing IDs.

Introduction to Using SSL Certificates and Use Cases

The kind of Certificate you need depends upon how your opentaps system will be used, and by whom. Web browser software on the end user's computer will react differently to a self signed certificate which carries your unverified identity and your encryption key, as compared to a Certificate Authority signed certificate which has verified your identity, and also carries your encryption key. This verification of your identity is the significant item of difference.

You have the choice of using either a do-it-yourself, self-signed certificate or of purchasing a Certificate Authority verified and signed SSL certificate. The end user's web browser (such as Firefox or Internet Explorer) comes equiped with its on list of Certificate Authorities and will usually accept your certificate signed by one of them, without raising any warning messages to the user.

• Typically, a self-signed certificate will be used when your users of opentaps are internal to your organization and operate mostly on the same internal network. They will have been trained in how to manage the web browser warning and permission messages that are produced when self-signed certificates are being used. (Refer to your web browser documentation for guidance on handling such messages.)
• A certificate purchased from a Certificate Authority, such as GeoTrust, GoDaddy, VeriSign and others would be required for communications with users who are unable or unwilling to work with an unverified company identity that is using a self-signed certificate. Their issue with self-signed certificates is that the user cannot tell whether or not your internet site is legitimate unless they have personal knowledge of your company.
• Thus, if opentaps will be used for eCommerce with a secure checkout procedure, a Certificate Authority issued certificate is likely the best option. This will give the user the required confidence in your legitimacy and also an error-free/warning-free user experience.

In opentaps configuration, whether using a self-signed or Certificate Authority signed and issued certificate, the same certificate is used for securely connecting to all parts of the opentaps system. Whether you are working in the various modules of the system, or your customers are shopping on your opentaps eCommerce site, the single certificate is controlling access and security for your user networks.

Configuring Your opentaps Server with an SSL Certificate

Information:  The following sections are for Technical System Administrators using the Linux 
command line functions.

There are several possible operational configurations for the opentaps server software, and the one you choose to implement will determine how the secure socket layer (SSL) Certificate will need to be installed.

We will begin by describing how to install your unique Certificate for opentaps simplest installation, which involves using the imbedded web server supplied in opentaps' pre-compiled, downloadable form for Linux.

Then, we will discuss some tips about how to handle the Certificates obtained in various formats from the authorities who sell "signed" and verified certificates. Finally, we will consider other possible opentaps installations and related Certificate issues.

Installing A Self Signed Certificate for the Default Linux Installation

To Use a Self-Signed Certificate You can create your own self signed SSL Certificate and install it for use with opentaps. To do so, you will use the keytool command provided in Linux which will produce a DER certificate, a DER Key, and store them into a Java Key Store (JKS) file suitable for the default web server delivered with opentaps (Tomcat). Thus, in this example, no file format conversions are required.

The following five steps are described in detail below:

• Create a Self-Signed Certificate

• Modify opentaps

• Restart opentaps

• Testing Your Certificate

Create a Self-Signed Certificate

The following exercise will produce a unique encryption key required for using secure opentaps communications, a self-signed X-509 (standard) identity certificate suitable for your business, and a keystore file for safe storage of the key and certificate. Because the certificate is self-signed rather than signed by a trusted Certificate Authority, users of your opentaps web site will still see a browser warning message telling them it has a self-signed certificate. If they know and trust you, they can then approve further access to your web site and will not see the warning again after the first approval.

This exercise makes use of the Java "keytool" provided by Sun Microsystems, and supplied in the Java JDK software required to run opentaps. For more information about keytool, refer to the command summary located at keytool commands.

Note: In the following list of questions from the keytool command, the requested "first and last name"
should be the name of your server host name, not your own name.  
*  For example, if you access your server as  
      http://localhost, or as
      http://localhost:8080
   then the answer is localhost.
*  If you use http://opentaps.mycompany.com:port#, then put opentaps.mycompany.com as the
   answer to "first and last name"

Run the following command and answer the questions presented as appropriate for your own company. You will be asked for two passwords, the first one is for the keystore (lock-box) that contains your finished certificate, the second one is for the encryption key. You can use the same password for both of these (recommended for simplicity). This keytool command produces a new "opentaps.jks" file which is the keystore with encryption key required for your installation. Execute the steps as shown in the following example:

In your Linux system change the directory to the opentaps installation directory, so that your opentaps.jks 
will be stored in the correct place on the file system,
$ CD /. . ./opentaps_home
Enter this command line, for a one year (365 day) certificate life,

$ keytool -genkey -alias opentaps -keyalg RSA -validity 365 -keystore framework/base/config/opentaps.jks

Respond to all these questions, 
Enter keystore password:  opentaps
What is your first and last name?
 [Unknown]:  localhost
What is the name of your organizational unit?
 [Unknown]:  Si Chen
What is the name of your organization?
 [Unknown]:  Open Source Strategies, Inc.
What is the name of your City or Locality?
 [Unknown]:  Los Angeles
What is the name of your State or Province?
 [Unknown]:  CA
What is the two-letter country code for this unit?
 [Unknown]:  US
Is CN=localhost, OU=Si Chen, O="Open Source Strategies, Inc.", L=Los Angeles, ST=CA, C=US correct?
 [no]:  yes

Enter key password for <opentaps>

       (Press only RETURN key if same as keystore password):  opentaps

Modify Opentaps File Names as follows

Now you must point opentaps to your new keystore file, opentaps.jks.

Modify the file framework/base/config/ofbiz-containers.xml under <property name="https-connector" value="connector">

From the original installation values which follow:

<property name="keystoreFile" value="framework/base/config/ofbizssl.jks"/>

<property name="keystorePass" value="changeit"/>

Enter these new values instead:

<property name="keystoreFile" value="framework/base/config/opentaps.jks"/>

<property name="keystorePass" value="opentaps"/>

Restart Opentaps Server

Stop the opentaps server and then restart it using the commands described in your installation instructions. On the Linux command line and in the opentaps installation directory:

./stopofbiz.sh      then, wait until the stopping process is completed
./startofbiz.sh     to restart the opentaps server.

Testing your Certificate Installation

Open a connection to your opentaps server using your own URL similar to https://URL:8443. (Do not connect using http://URL:8080 as this is the non-secured connection to the server). You will likely receive a certificate warning message. This is because your browser does not have a client certificate that recognizes your self-signed server certificate. If required by your browser, approve the exception and connect to your server. Regardless of the warning, your connection should be a secure SSL connection and your web browser should display its small "lock" symbol indicating this fact.

Note: To facilitate future configuration for your company server, you can put the keystore or 
JKS file (opentaps.jks in this exercise) in the hot-deploy/ component for your own company, 
instead of framework/base/config/ folder.

Installing A Purchased CA-Signed Certificate for the Default Linux Installation

The default opentaps installation is facilitated in the pre-compiled download package, which runs on the Tomcat web server included in the package. Installation of this default option is very simple. One of the examples that follow will explain the simplest CA-signed certificate installation method for it, using PKCS12 format.

This discussion assumes that you need to purchase your verified and signed certificate from a Certificate Authority (CA) that is well known to the industry, specifically the web browser software providers should have your chosen CA listed in their browser certificate configuration file. Then, when your CA-signed certificate is properly installed in opentaps it will produce a user experience free of any warning messages regarding your web site or your identity.

To obtain such a certificate, you will choose a Certificate Authority to provide it, and follow their directions for submitting your request, which will include unique company information, and a private key that you will need to generate using tools available on Linux or supplied by your CA.

Because you may encounter a variety of file formats, and procedures for installing your certificate, depending upon which CA you choose to work with, and which tool set they recommend, we will provide two examples for how this process flows:

• Example 1 -- Installing a CA-signed certificate using PKCS12 format for Tomcat

• Example 2 -- Installing a certificate using PEM format from the CA with format conversion and a keystore import step using a 3rd party tool.

Example 1 Using a PKCS12 Certificate with Tomcat Server

The Certificate Authority will often provide options for your certificate format, or for the web server type where it will be installed. Choose the option that fits your installation of opentaps, for this example we are using the Tomcat server that is included in the opentaps download package.

In this case, you can follow the instructions provided by the Certificate Authority for use of their signed certificate with Tomcat, except that configuration of the server will be accomplished in an opentaps file rather than the usual Tomcat file. The following will describe the needed steps in this procedure.

Note1: Make sure to locate the keystore file within your opentaps installation directory somewhere, so
that the opentaps system can find the needed items. 

Note2: These steps use the "openssl" Linux command line tool which is an open source project that provides free 
download software for your Linux system in case you need to install it.

Note3: Choose a Certificate Authority that is listed in your the web browser listing of such authroities.
This is to make sure your server certificate will function without causing any web browser warning messages
that your opentaps users might see. 

The outline of the steps is as follows,

1. You will use openssl to create an encryption key pair on your server and save it for reference in the next step.
2. You will use openssl to create a Certificate Request (CSR) file that references your encryption key file, and also includes your unique Identification information for making an SSL Certificate.
3. You will submit the CSR file to the Certificate Authority you have chosen, following their instructions on how the submission is to be processed. (We tested this procedure with a GoDaddy Certificate.)
4. You will follow the CA's instructions to obtain and download the completed (signed) certificate package to your opentaps server computer. If needed, unpack (unzip) the certificate package in the opentaps sub-directory you are using for this procedure.
5. You will use openssl to reference the contents downloaded from the CA and to combine the results into a java type "keystore" file that Tomcat will reference for identification and encryption purposes.
6. You will perform the configuration steps needed to point to your keystore file in the opentaps system file specified in these instructions, not in the usual Tomcat file used for configs.

Step-By-Step Details:

0. Make your current directory the opentaps installation directory.

1. Create the encryption key file like this:
     openssl genrsa -out privatekey.pem 4096

2. Create the CSR file like this:
     openssl req -new -key privatekey.pem -out cert.csr

3. Submit the cert.csr file to the CA you selected using their detailed instructions. 

4. Retrieve your signed certificate package from the CA according to their instructions. 
     Download this to your Linux server that will host opentaps installation with Tomcat.
     Unpack (unzip) the CA material you downloaded.
     In the next step you will use the downloaded file gd_bundle.crt from your CA package to create
       a new keystore file in the PKCS12 format which works with Tomcat.

5. Create your keystore file for Tomcat using the downloaded material from your CA, like this:
     openssl pkcs12 -export -chain -CAfile gd_bundle.crt -in <name you gave for your server certificate goes here> 
     -inkey <path and name of your private key file goes here> 
     -out <name your new keystore file like keystore.tomcat here> 
     -name <put a nickname here like tomcat> -passout pass:<specify a password here>

   Note: This saves keystore.tomcat in your current directory (the opentaps installation directory).
   If you have specified a sub-directory for the keystore file, remember that for the next step.

6. Configure the pointer that the opentaps Tomcat web server will use to access your keystore file's 
information like this:
     a) From your opentaps installation directory, open framework/base/config/ofbiz-containers.xml
        using your text editor.
     b) Find <property name="https-connector" value ="connector"> which is near the bottom of the file.
     c) Modify the following entries as shown here:
        1)   <property name="keystoreFile" value="keystore.tomcat"/>
        2)   <property name="keystorePass" value="password you specified goes here"/>
        3)   <property name="keystoreType" value="PKCS12"
     d) Save this modified file.

7. Stop and then Re-start the opentaps server which will restart Tomcat also, like this:
     a) from the opentaps installation directory,
     b) ./stopofbiz.sh   then, wait for the stopping process to complete, then restart,
     c) ./startofbiz.sh 

8. Test the Server Certificate 
   Use the server name that you provided in your certificate identity information, such as myserver.mydomain.com, 
   and make a connection to your opentaps server like this:
        https://myserver.mydomain.com:8443/opentaps/ 
        This should bring up the opentaps log-in screen without displaying any warning messages.

Example 2 Using a PEM Certificate with Conversion for Tomcat

The different Certificate Authorities (CA) use a variety of procedures and they produce certificate packages using different file formats. As a consequence it becomes necessary to use various tools, sometimes including file format conversion tools available in the open source community. This example is about one of those situations.

Here we assume that the CA has returned our certificate package contents in the PEM format, which we then convert and use to create a java type keystore file. In this example we use the following tools:

• openssl -- an open source community tools that can be downloaded
• keytool -- from Sun Microsystems included in their JDK download package that is required to run opentaps
• ImportKey.java -- which can be obtained from number of sites online, including agentbob.info at this URL http://www.agentbob.info/agentbob/79-AB.html

Submitting Your Request File

As an example only, the command for generating your own private encryption key using the openssl command for linux, might look like this:

openssl genrsa -out key.pem 4096

This produces a pair of keys of length 4096 in the file key.pem which is stored in your current directory. You will also need to produce the certificate request file that goes to the Certificate Authority:

openssl req -new -key key.pem -out cert.csr

This produces a certificate request (.csr file) using your newly created key.pem file as one input, plus other information you must provide. In the case of a specific Certificate Authority you have chosen, you will follow their directions carefully for these last two steps.

Warning: If you need to open and view the files produced here for any reason, such as
to cut and past the content for CA submission, use only basic text editors, never us
an advanced word processor -- which may insert invisible characters or changes to
your files rendering them corrupted, and unusable for this purpose.

In our example, when your certificate comes back from the CA it may be in PEM format, unless your requested another another format. A PEM certificate file looks something like this and it includes the Begin line and the End line as part of the content:

---

BEGIN CERTIFICATE-----

MIIDVzCCAsCgAwIBAgIDD96eMA0GCSqGSIb3DQEBBQUAME4xCzAJBgNVBAYTAlVT WjCB4zEpMCcGA1UEBRMgbTc1VVk4QzNPMXhabnYtNkhNLTMwTDZWTXg2QnVuRVkx CzAJBgNVBAYTAlVTMRMwEQYDVQQKEwpjdnJ1cHMuY29tMRMwEQYDVQQLEwpHVDYy ODAxNzcwMTEwLwYDVQQLEyhTZWUgd3d3Lmdlb3RydXN0LmNvbS9yZXNvdXJjZXMv MRAwDgYDVQQKEwdFcXVpZmF4MS0wKwYDVQQLEyRFcXVpZmF4IFNlY3VyZSBDZXJ0 aWZpY2F0ZSBBdXRob3JpdHkwHhcNMTAwMzE1MDQwNDI0WhcNMTEwMzE3MTM1OTU1 MRAwDgYDVQQKEwdFcXVpZmF4MS0wKwYDVQQLEyRFcXVpZmF4IFNlY3VyZSBDZXJ0 aWZpY2F0ZSBBdXRob3JpdHkwHhcNMTAwMzE1MDQwNDI0WhcNMTEwMzE3MTM1OTU1 MRAwDgYDVQQKEwdFcXVpZmF4MS0wKwYDVQQLEyRFcXVpZmF4IFNlY3VyZSBDZXJ0 aWZpY2F0ZSBBdXRob3JpdHkwHhcNMTAwMzE1MDQwNDI0WhcNMTEwMzE3MTM1OTU1 MRAwDgYDVQQKEwdFcXVpZmF4MS0wKwYDVQQLEyRFcXVpZmF4IFNlY3VyZSBDZXJ0 aWZpY2F0ZSBBdXRob3JpdHkwHhcNMTAwMzE1MDQwNDI0WhcNMTEwMzE3MTM1OTU1

---

END CERTIFICATE-----

Installing Your Certificate

To actually use your PEM certificate in opentaps you must load it into a Java KeyStore (JKS) file, from which the opentaps Tomcat web server will make use of it. The content of this JKS is required to be in DER format, which is the binary version of your certificate. Download your two files from the CA (a cert file and a key file) into your opentaps installation directory.

Since your certificate is in PEM format you will need to convert it to DER and then load it into your Java KeyStore (lock-box) file. You may receive two files from the CA with names similar to these:

• key.pem which is the private key file in PEM format
• cert.pem which is the certificate file in PEM format

* Run the following two commands to convert each of these two files into DER format:

$ openssl pkcs8 -topk8 -nocrypt -in key.pem -inform PEM -out key.der -outform DER

$ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER

This produces the two files in the format (DER) required for your opentaps Java KeyStore (JKS) file.

* The next step is to import these two files into the Java KeyStore file using a Java program 
called ImportKey.  Run the following command:

    $ java ImportKey key.der cert.der
    Using keystore-file : /home/user/keystore.ImportKey
    One certificate, no chain.
    Key and certificate stored.
    Alias:importkey  Password:importkey

This creates your keystore file called keystore.ImportKey and it imports the two component files into it. But, it uses a default password which needs to be changed.

* Now, change the password on the keystore to "opentaps" or other password of your choosing, 
  using this command:

    $ keytool -keystore keystore.ImportKey -storepass
    Enter keystore password:importkey
    New keystore password:opentaps
    Re-enter new keystore password:opentaps

Modify opentaps

Once you have the keystore file ready, the next step is to edit the file framework/base/config/ofbiz-containers.xml and put in the location of your keystore.ImportKey file update to the current password. Note that you can put the keystore file in the hot-deploy/ component for your own company, instead of framework/base/config/ to facilitate future maintenance of your company configuration files. Step-By-Step

Configure the pointer that the opentaps Tomcat web server will use to access your keystore file's 
information like this:
    a) From your opentaps installation directory, open framework/base/config/ofbiz-containers.xml
       using your text editor.
    b) Find <property name="https-connector" value ="connector"> which is near the bottom of the file.
    c) Modify the following entries as shown here:
       1)   <property name="keystoreFile" value="keystore.ImportKey"/>
       2)   <property name="keystorePass" value="password you specified goes here"/>
       3)   <property name="keystoreType" value="JKS"
    d) Save this modified file.

Restart opentaps

* Stop and then Re-start the opentaps server which will restart Tomcat also, like this:
    a) from the opentaps installation directory,
    b) ./stopofbiz.sh   then, wait for the stopping process to complete, then restart,
    c) ./startofbiz.sh 

Test the Server Certificate

* Use the server name that you provided in your certificate identity information,
  such as myserver.mydomain.com, and make a connection to your opentaps server like this:
       https://myserver.mydomain.com:8443/opentaps/ 

This should bring up the opentaps secure log-in screen without displaying any warning messages on the users browser, if all has gone well in the procedures.