2 Installation

This chapter describes the installation of Rest API and covers the following topics:

• Prerequisites

• Installing EFTLink Rest API

Prerequisites

This section assumes you have already configured EFTLink following the instructions set out in the Oracle Retail EFTLink Framework Installation and Configuration Guide.

Java

EFTLink Rest API will run with any version of Java from 1.8.

The Rest API by default expects Java jre to exist in the folder location C:\jre (on Windows) or /opt/jre (on a Linux kernel).To change the default location of java you will need to update either include-eftlink-rest-api-windows.conf or include-eftlink-rest-api-linux.conf which are located in <installation directory>\wrapper\conf.

Installing EFTLink Rest API

Note:

All files necessary, are already in place so long as you have completed the instructions set out in the Oracle Retail EFTLink Framework Installation and Configuration Guide.

• Setting up Jetty for SSL Communication

• Creating a Key Store File with Self-Signed Certificate

• Obfuscating Text using Jetty

• Installing as a Service

• Self-Signed Certificate Trust

Setting up Jetty for SSL Communication

• Out of the box, the Rest API will only allow SSL communication. However, you are required to setup a key store that includes a server certificate.

• The certificate can be either a self-signed (for internal testing use only) or signed by known third party Certificate Authority (CA) vendor like Verisign.

• See Creating a Key Store File with Self-Signed Certificate details below on how to create a self-signed certificate.

• Once the eftlink-rest-api "keystore" file has been created, you will need to obfuscate the password (See Obfuscating Text using Jetty section below).

• Once you have the obfuscated password, open the jetty.xml file located in the root of the eftlink installation directory.

• Replace the text ObfuscatedPasswordHere with your obfuscated password.

  For example,

  <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">

  …

  <Set name="KeyStorePassword">ObfuscatedPasswordHere</Set>

  <Set name="KeyManagerPassword">ObfuscatedPasswordHere</Set>

  <Set name="TrustStorePassword">ObfuscatedPasswordHere</Set>

  …

  </New>

Creating a Key Store File with Self-Signed Certificate

1. Open a command terminal.

2. Navigate to C:\eftlink\keys or any other directory.

3. Execute the command below. The command will ask of your first and last name (Common Name or CN).

   Enter the machine name or localhost. Populate the other details. The alias below, "<alias name> " need to be replaced and can be anything.

   The sample password below is "<password> ". You can use any password you desire for your key store and certificate. Just take note of them as we need to obfuscate them later.

   The command will produce the key store file, eftlink-rest-api.keystore on the current directory.

   C:\jre\bin\keytool -genkey -keyalg RSA -alias <alias name> -keystore eftlink-rest-api.keystore -storepass <password> -validity 360 -keysize 2048

4. The output file needs to be copied in C:\eftlink\keys if it's not there yet. Create the keys directory if needed.

Obfuscating Text using Jetty

1. Assuming that EFTLink is already installed at C:\eftlink, open a command terminal and navigate to C:\eftlink\lib.

2. Execute the command below. The parameter 'Password' is your desired password to obfuscate.

   If Jetty is upgraded in the future, replace the filename(jetty-util-9.4.27.v20200227.jar) below.

   java -cp jetty-util-9.4.27.v20200227.jar org.eclipse.jetty.util.security.Password Password

3. Sample output below. We are interested with the OBF version.

   Password

   OBF:1eam1lmn1hv41ink1uh21ugo1iku1hse1lj31e8w

   MD5:2d6df80067293fb807d8adc12fa17650

Installing as a Service

This section describes how to install EFTLink Rest API as a service.

Windows Configuration

It is possible to install EFTLink Rest API as a windows service, using a third-party wrapper. EFTLink is distributed with a version of Tanuki Software Limited Java Service Wrapper.

Follow the steps below on how to configure EFTLink to run as a Windows service.

1. Installing the Service.

   1. From a command line (with administrative privileges) change to the root directory for EFTLink. For example, type cd /eftlink.

   2. To install EFTLink Rest API as a window service, type eftlink-rest-api install.

      If there are problems during install, it is possible to remove the service by typing eftlink-rest-api remove. This may be necessary if the service is previously installed in a different folder. The service may then be reinstalled at the correct location by entering eftlink-rest-api install.

   3. Once installed the service can be started and stopped from a command line:

      Eftlink-rest-api start

      Eftlink-rest-api stop

      The service can also be controlled from the Windows Services Control Panel applet (Rest API).

2. Examine the log file Wrapper.log.

   1. The log file can be found in the designated EFTLink folder\log\eftlink-rest-api_ wrapper.log

   2. Installing, starting the service, stopping the service, and uninstalling the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.

Linux Configuration

It is possible to run EFTLink-rest-api as a service, using a third-party wrapper. EFTLink-rest-api is distributed with a version of Tanuki Software Limited Java Service Wrapper.

Note:

You may be required to give script file(s) execution rights. This can be accomplished by opening a terminal window and typing:

sudo chmod +x <PathToFile>

for example, sudo chmod +x /opt/eftlink/eftlink-rest-api.sh

Follow the steps below on how to configure EFTLink to run as a service.

1. Running EFTLink-rest-api.

   1. From a terminal change to the directory for EFTLink.

      For example, type cd /opt/eftlink.

   2. To run EFTLink-rest-api as a service from a terminal type the following command sudo./eftlink-rest-api.sh start.

   3. To stop, check the status or to restart EFTLink-rest-api from a terminal, type one of the following commands: sudo./eftlink-rest-api.sh stop sudo./eftlink-rest-api.sh status sudo./eftlink-rest-api.sh restart sudo./eftlink-rest-api.sh condrestart

2. Examine the log file Wrapper.log.

   1. The log file can be found in the designated EFTLink folder\log\eftlink-rest-api_ wrapper.log

   2. Starting the service and stopping the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.

Self-Signed Certificate Trust

To trust the self-signed certificate in your browser:

1. Open your browser (for example, Google Chrome).

2. Ensure the REST API is running.

3. Navigate to https://localhost:8443/.

4. The browser will warn you that your connection is not private. Click on Advance.

5. Click Proceed to localhost (unsafe).

6. Disregard the 404 not found error.

Your browser is now ready to talk to the REST API using the client.html or custom_form.html file.