2 Installation

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

• Prerequisites

• Configuring 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

Important

The EFTLink Framework is compatible with Java 11 and later, whereas the EFTLink Rest-API service requires a minimum of Java 17 due to the required Jetty dependencies.

By default, the EFTLink Rest-API service uses the same location for the Java runtime as the EFTLink Framework and, as such, expects a Java runtime (JRE) to be located at C:\jre (on Windows) or /opt/jre (on Linux).

To change the default location for the EFTLink Rest-API service, follow these steps:

1. Update the include-eftlink-rest-api-windows.conf or include-eftlink-rest-api-linux.conf file located in <installation directory>\wrapper\conf, setting:

   Example: JAVA_HOME=<full path to Java 17>

2. Update the eftlink-rest-api.bat or eftlink-rest-api.sh file in <installation directory>, setting:

   Example: wrapper.java.command=<full path location to Java 17>

Configuring 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

• API Key Authentication

• Creating a Key Store File with Self-Signed Certificate

• Obfuscating Text using Jetty

• Running EFTLink Rest API

• Self-Signed Certificate Trust

Setting up Jetty for SSL Communication

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

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

2. Once the eftlink-rest-api "keystore" file has been created, you will need to obfuscate the password.

   See the Obfuscating Text using Jetty section below.

3. Replace the text ObfuscatedPassword Here 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>

API Key Authentication

The Rest API uses an API Key for authentication. The steps below must be followed for API requests to be authenticated.

1. Generate an API Key.
2. Add APIKey=<OBFAPIKey> to the eftlink-rest-api.properties file, where <OBFAPIKey> is the obfuscated value of your API Key. See the Obfuscating Text using Jetty section below.
3. Consumers must send two subprotocols in the initial HTTP request: "oracle.eftlink.rest.api.key", which will be the negotiated subprotocol, and "oracle.eftlink.rest.api.key. <Base64URLAPIKey>", where <Base64URLAPIKey> is the base64Url-encoded SHA-384 hash of your API Key.

Linux Command:

echo -n '<API_KEY>' | openssl dgst -sha384 -binary | base64 | tr '+/' '-_' | tr -d '='

PowerShell Command:

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('<API_KEY>') | % { [System.Security.Cryptography.SHA384]::Create().ComputeHash($_) }) -replace '\+', '-' -replace '/', '_' -replace '=', ''

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. Before executing the command below, replace <java> with the location to your JDK version and replace <alias name> with a meaningful alias. Also, replace <password> with your desired password for the keystore and certificate. Make sure to note it down, as we will need to obfuscate it later.

4. Execute the command below. The command will ask of your first and last name (Common Name or CN). Enter the machine name or localhost and populate the other details.

5. Once you have provided all the information (CN, OU, O, L, ST, C), confirm that it is correct.

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

   Command:

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

Obfuscating Text using Jetty

1. Open a command terminal.

2. Navigate to the <eftlink installation directory>\lib directory.

3. Before executing the command below, replace <java> with the location to your JDK version and replace <username> with a meaningful value. Also, replace <password>. The parameter <password> is your desired password or string you wish to obfuscate.

4. Execute the command.

   <java>\bin\java -cp jetty-util-12.0.14.jar org.eclipse.jetty.util.security.Password <Username> <Password>

   The output should look something like below. Note that we are only interested in the OBF value for the purposes of this document.

   OBF:1oq31uum1xtv1zej1zer1xtn1uvk1or7

   MD5:Dc647eB65e6711E155375218212b3964CRYPT:efE.3y6/wNpn6

Running EFTLink Rest API

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. Install the Service.

   1. Open a command terminal.

   2. Navigate to the <eftlink installation directory> directory.

   3. To install EFTLink Rest API as a window service, enter eftlink-rest-api install.

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

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

      eftlink-rest-api start

      eftlink-rest-api stop

   6. 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 in <eftlink installation directory>\log and is called eftlink-rest-api_wrapper.log.

   2. Installing, starting the service, stopping the service, and uninstalling the service are all briefly logged in eftlink_wrapper.log. 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, enter cd /opt/eftlink.

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

   3. To stop, check the status, or to restart EFTLink-rest-api from a terminal, enter 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. This can be used to diagnose any problems.

Self-Signed Certificate Trust

To trust the self-signed certificate in your browser:

1. Start EFTLink and EFTLink-Rest-API service.

2. Open your browser.

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.

7. Your browser is now ready to communicate with the REST API using your code in the HTML file.

8. As an additional check to ensure the REST API service is running, you can perform a ping-pong test.

9. Enter https://localhost:8443/ping into your browser.

   You should receive a “pong” response.