1. Border Control Installation and User Guide
  2. Installing Cruise Property Management Border Control Rest API/Web Application Server
  3. Preparing Java Environment

1 Preparing Java Environment

Before you install the Cruise Property Management Border Control Version 23.1 API / Web App server,

  1. Ensure the JDK is installed.

  2. Ensure that you have a tool for manipulating certificates installed.

Set JAVA_HOME or JRE_HOME variable

  1. Search Environment Variables in the search box (next to the Windows start button) then select Edit to edit the system environment variable.

  2. Click the Environment Variables button.

  3. Under System Variables, click New.

  4. In the Variable Name field, enter either of the following:

    • JAVA_HOME if you have the JDK (Java Development Kit) installed

    • JRE_HOME if you have the JRE (Java Runtime Environment) installed.

  5. Browse the Directory and select “C:\Program Files\Java\[java version]”

  6. Click OK to apply the changes.

Setting the JAVA Path

  1. Search Environment Variables then select Edit to edit the system environment variable.

  2. Click the Environment Variables button.

  3. Find the ‘Path’ from the System Variable and click Edit then select New.

  4. Browse directory “C:\Program Files\Java\[java version]\bin”

  5. Click OK to apply the changes.

Installation Process

Installation is a three-step process, where:

  • Step 1: Create a Java keystore containing certificates purchased from a reputable Certificate Authority

  • Step 2: Generate security keys for OAuth

  • Step 3: Install the software

Create Java Keystore for Cruise Property Management Border Control API/Apps Server

Background

Java Keystore is required to store private keys and certificates used by the Cruise Property Management Border Control API/Web App. A Java Keytool is used to create a Java Keystore. Java Keytool is distributed as part of the Java JDK. Java Keystore files can be generated on any machine. They need not be on the same server where the SSL/TLS certificate will be installed.

Important: In this section, we use OpenSSL to demonstrate the process. You should select a certification manipulation tool that meets your organization’s security policy.

Recommendations

It is recommended that you generate a new Keystore following the process outlined in this section. Installing a new certificate to an existing Keystore often ends in installation errors or the SSL/TLS certificate not working properly. Before you begin this process, backup and remove any old Keystores.

The act of generating a self-signed Digital Certificate to identify the Cruise Property Management Border Control API/Web app is not recommended for the production environment. It increases the risk of an unscrupulous party impersonating the Cruise Property Management Border Control API/Web App to steal sensitive information. However, for limited, non- production testing of Cruise Property Management Border Control API/Web app, you could use a self- signed certificate despite the increased security risk. However, do so at your own risk: this is not recommended.

Generate a new Java Keystore using Java Keytool

  1. Navigate to the directory where you plan to manage your Keystore and SSL/TLS certificates.

  2. Run the following command:

    keytool -genkey -alias <ALIAS> -keyalg RSA -keysize 2048 -keystore <SITE_NAME>.jks –ext SAN=dns:<SITE_NAME>

  3. In the command above, <SITE_NAME> is the name of the domain you want to secure with the SSL/TLS certificate. The command will generate the Keystore with the public and private key pair and a self-signed certificate for the server. . <ALIAS> is the name for this newly generated entry in the Keystore.

  4. You will be prompted to create a password for the new Keystore.

  5. Enter the SSL/TLS certificate information for the self-signed certificate.

    1. When prompted for the first and last name, enter the Fully Qualified Domain Name (FQDN) for the site you wish to secure with the SSL/TLS certificate. For example, www.yourdomain.com or mail.yourdomain.com. If the SSL/TLS certificate is a Domain wildcard type, the FQDN is *.yourdomain.com.

    2. Enter the Common Name (CN), for example, The FQDN.

    3. Enter the Organizational Unit (OU), for example, Cruise Operation

    4. Enter the Organization (O), for example, Cruise Company

    5. Enter the Locality (L), for example, Redwood City

    6. Enter the State or Province Name (S), for example, California

    7. Enter the Country Name (C), for example. US

    8. You will be prompted to verify all the information entered. Type ‘y’ or ‘yes’ to confirm.

    9. Enter the Keystore password when prompt. The new Keystore file <SITE_NAME>.jks is now available in the current working directory.

Generate a Certificate Signing Request (CSR) using Java Keytool

  1. Navigate to the directory where the Keystore was generated earlier.

  2. Run the following command:

    keytool -certreq -alias <ALIAS> -file csr.txt -keystore <SITE_NAME>.jks –ext SAN=dns:<SITE_NAME>

  3. In the command above, <SITE_NAME> is the name of the Keystore generated in earlier section, and <ALIAS> is the name of the entry in the Keystore that defined in earlier section. The CSR will manifest itself as an output file based on the certificate info entered earlier. You will also need to enter the Keystore password to proceed.

  4. The CSR output file is in the same working directory, for example, <SITE_NAME>.txt.

Backing Up the Keystore

Save and back up the Keystore file to a safe, secure location.

Importing SSL/TLS Certificate to the Keystore

After receiving your SSL/TLS certificate from Certificate Admin, you must import the SSL/TLS Certificate file to the same Java Keystore under the same alias name (for example, alias server) used to generate your CSR. If you try to install the certificate to a different keystore or under a different alias, the import command will not work.

Note:

Before importing the SSL/TLS certificate, ensure the certificate chain format is appropriate and valid. You can use OpenSSL tool to check on the validity as follows: 

openssl pkcs7 –print_certs –in <cert_name>.p7b

  1. Navigate to the directory where the Keystore was generated earlier.

  2. Run this command:

    keytool -import -alias <ALIAS>-file <CERT_NAME>.p7b -<SITE_NAME>.jks

  3. In the command above, <CERT_NAME> is the name of the SSL/TLS Certificate. <SITE_NAME> is the name of the Keystore generated in earlier section. <ALIAS> is the name of the entry in the Keystore that defined in earlier section.

  4. You will get a confirmation message that displays “Certificate reply was installed in keystore.” Type ‘y’ or ‘yes’ to proceed.

  5. This will load all the necessary certificates to the Keystore.

  6. The Keystore is now ready to be used by the Tomcat/Tomcat Embedded Server.

Create Key Pair for Cruise Property Management Border Control API Authentication

Background

OAuth 2.0 is the user authorization mechanism used by Cruise Property Management Border Control API. It requires a generation of an asymmetric key pair to work. The asymmetric key pair is used to securely sign and read contents found in the Security token. Security of the API relies on the security token. API calls made without a valid Security token will be rejected. In detail, the security token contains a checksum. This checksum ensures that the token is not tampered with. The checksum is calculated by adding up the bytes in the security token and is signed by the private key. A third party can check the validity of a token by recalculating the checksum, decrypting the original checksum with the public key, and comparing the two. Any differences between the two checksums indicates that the token has been tampered with.

Note:

We provide the process below as an example. You can use other certificate manipulation tools to generate the public and private keys. Whichever tool you use, ensure that you download them from a reliable source and that the downloaded tool is security checked, virus scanned, and checksum checked. Without such due diligence, you may compromise the security of your installation.

Generating a new Key Pair using JSON Web Key Generator

  1. Go to https://mkjwk.org/ for the JSON Web Key generator tool.

  2. Select the RSA tab.

  3. Select the right Key Size in bits, required for RSA key types. Recommended size is 2048 and above.

  4. Select the Key Use as signature.

  5. Select the Key ID as specify and enter any string, for example sign-rsa.

  6. In the ShowX.509, select No

  7. Copy the ‘Public Key’ and “Public and Private Keypair Set” into a separate files with .json extension and save.

  8. Sample public and private keys are shown below.

    Sample Public key:

    {
   "keys": [
       {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "sign-rsa",
          "alg": "RS256",
          "n": "g88SjdDsfdHd64fdf..."
      }
    ]
}

    Sample Private key:

    {
  "keys": [
      {
          "p": "5BjdvhhdGjjjdsUI...",
          "kty": "RSA",
          "q": "k-7TihGsdfjnjLLf8...",
          "d": "e4t4J7dfk7jddPo78...",
          "e": "AQAB",
          "use": "sig",
          "kid": "sign-rsa",
          "qi": "UlYwJ6Jsdfsdfc...",
          "dp": "CDz5rYYsdffffI1...",
          "alg": "RS256",
          "dq": "fBAEeUP98HHdf...",
          "n": "g88SjLLjsdf881IP..."
      }
    ]
}