Appendix A. PostgreSQL

A.1 Install PostgreSQL

Note
In the examples, we refer to PostgreSQL-9.6. In the subsequent commands, you should replace the version number with the version that you are using.

Installation of PostgreSQL requires the following “yum install” steps.

sudo yum -y localinstall http://yum.postgresql.org/<Postgresql version>.rpm
sudo yum install postgresql96-server
sudo yum install postgresql-contrib

A.2 Start PostgreSQL as a Service

Start PostgreSQL per your Linux Platform (RHEL 7+ and CentOS):

sudo /usr/pgsql-9.6/bin/postgresql96-setup initdb
sudo systemctl start postgresql-9.6.service

Verify that PostgreSQL service shall start automatically when the OS (re)starts:

sudo systemctl enable postgresql-9.6.service

A.3 Tweak PostgreSQL Permissions

1. Edit /var/lib/pgsql/9.6/data/pg_hba.conf as follows:
• Set all METHOD(s) to trust.
• Add a new entry to the table.
  host    all             all             0.0.0.0/0        trust

The file should show the following entries:

# TYPE  DATABASE        USER            ADDRESS         METHOD
# "local" is for Unix domain socket connections only
local   all             all                              trust
# IPv4 local connections:
host    all             all             127.0.0.1/32     trust
# IPv6 local connections:
host    all             all             ::1/128          trust
host    all             all             0.0.0.0/0        trust

2. Edit /var/lib/pgsql/9.6/data/postgresql.conf as follows:
   Set the listen_address as follows:

   #----------------------------------------------------------------
   # CONNECTIONS AND AUTHENTICATION
   #----------------------------------------------------------------
   listen_addresses = '*'          # what IP address(es) to listen on;
                                   # (change requires restart)
   #port = 5432                    # (change requires restart)

Appendix B. PIM – Using the Password Plugin

A PIM is an external server that keeps passwords and provides an API for password retrieval. If your password management policy requires keeping passwords in a PIM, contact Unbound Support for the development of a connector matching your PIM system.

This section documents one possible implementation of this capability.

To install PIM connector files:

1. Unpack the pimconnector package.

tar xvfz pimconnector.<version>.tar.gz

2. Move the extracted files.

sudo mv pimconnector.jar /var/lib/dymobile/plugin
sudo mv a2astub.jar /var/lib/dymobile/plugin

3. Make two copies of a2a.conf and place them in a location of your choice. For example:

cp a2a.conf /home/user/a2a_db.conf
cp a2a.conf /home/user/a2a_jks.conf

4. Update /etc/dymobile/dymobile.conf.

# Dyadic Configuration
enc.keystore.type=jks
# enc.keystore.provider=
enc.keystore.file=/etc/dymobile/dyadic.jks
enc.keystore.password=
enc.key.alias=dyadic
enc.key.password=
db.cred.conf=/home/user/a2a_db.conf
jks.cred.conf=/home/user/a2a_jks.conf
a2a.jar=a2astub.jar

Additionally:

• The db.cred.conf key points to the configuration file that retrieves the database password. Edit a2a_db.conf to change the password.
• If you are encrypting the database keys using an external JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption., the jks.cred.conf key points to the configuration file that retrieves both the JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. and key passwords. Edit a2a_jks.conf to change the password.
• The 2a2.jar key refers to the implementation JAR that pimconnector loads. Remember to replace the stub pim library with the production version when switching to production.
• If additional servers are used, you must copy the existing JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. file and the current dymobile.conf configuration file to all servers before starting the Tomcat server.

Appendix C. Securely Transfer OTP Seed

To create an RSA key pair for securely transferring a new one-time password (OTPOne-Time Password (or Pin) - a password that is valid for only one login session or transaction.) seed:

1. Run the following commands to create an RSA 2048 key pair and a public key:

openssl genrsa 2048 > key.pem
openssl rsa -in key.pem -pubout > key.pub

2. Run the following command to import the key into the server:

mobilecl imp-otp-pubkey -i key.pub

3. If using the OTPOne-Time Password (or Pin) - a password that is valid for only one login session or transaction. generation workflow, copy the key pair including the private key (key.pem) to the OTPOne-Time Password (or Pin) - a password that is valid for only one login session or transaction. server.

Note
In a production environment, it is required to remove the private key from the Unbound server.

Appendix D. Upgrade Procedures

This section contains two topics:

• Upgrade from 1.2.17xx releases that precede the 1.2.1709.2 release to a subsequent release.
• Upgrade from releases preceding release 1.2.1701 to release 1.2.1701.

D.1 Upgrade from Releases Preceding 1.2.1709.2

CORE Virtual Enclave Server version 1.2.1709.2 is backward compatible with the previous EKPDyadic Endpoint Key Protection (EKP). This product was rebranded as Unbound Crypto-ot-Things (CoT) 1.2 client devices.

D.1.1 Upgrade CORE Virtual Enclave Database Schema

1. Extract Unbound Mobile Schema archive.

tar xvfz mobile-schema.xxxx.yyyy.tar.gz

Obtain the following schema-update files:

dyadic-oracle-upgrade-from-1.2-to-1.2.1709.sql
dyadic-postgresql-upgrade-from-1.2-to-1.2.1709.sql

2. Apply the relevant SQL update script file for the database being used. For example, run the dyadic-oracle-upgrade-from-1.2-to-1.2.1709.sql script to upgrade the schema on the Oracle database.

D.1.2 Upgrade CORE Virtual Enclave Server Software

1. Use rpm to upgrade dymobile package:

rpm -Uvh dymobile-1.2-xxxx.yyyy.RHES.x86_64.rpm

Warning
Use the –force flag when upgrading from older releases identified with the following release format: 1.2.<four or five digit build number>.

2. Upgrade Unbound Mobile Server .war file by copying it to the appropriate location in the Tomcat “webapps” folder:

cp /opt/dyadic-mobile/dyadic-mobile-server.war \
/usr/local/tomcat/webapps/dyadic-mobile-server.war

D.2 Upgrade from Releases Preceding 1.2.1701

This chapter describes the upgrade process from Dyadic Mobile releases 1.0 or 1.1 to Dyadic Mobile release 1.2. To upgrade, perform the following steps:

1. Upgrade the database schema.
2. Upgrade CORE Virtual Enclave server software.
3. Update logs mechanism.
4. Optionally:
• Enable storage encryption.
• Enable client settings feature.

Note
This is an independent upgrade.

Note
It is possible to perform the upgrade “one stage at a time.”
For example, it is feasible to update the database schema independent to upgrading the CORE Virtual Enclave software.

In this section, we assume the Tomcat base directory is: /usr/local/tomcat.

D.2.1 Obtain the Dyadic Mobile package

1. Obtain from Unbound: mobile-all.1.2.xxxx.yyyy.tar.gz
2. Extract the package.

tar xvfz mobile-all.1.2.xxxx.yyyy.tar.gz

The following files are extracted:

• mobile-schema.1.2.xxxx.yyyy.tar.gz – Archive that holds Unbound SQL Schemas.
• mobile-kit.1.2.xxxx.yyyy.tar.gz – Archive that holds JDBC drivers and Tomcat log extensions.
• dymobile-1.2.xxxx.yyyy.RHES.x86_64.rpm – The Unbound Mobile Software installation.

D.2.2 Upgrade the Database Schema

1. Extract Unbound Mobile Schema archive.

tar xvfz mobile-schema.xxxx.yyyy.tar.gz

Among other files it has the following schema-update files:

dyadic-oracle-upgrade-to-1.2.sql
dyadic-postgresql-upgrade-to-1.2.sql

2. Apply the relevant SQL update schema file for the database being used. For example, apply the dyadic-oracle-upgrade-to-1.2.sql script to upgrade the schema on the Oracle database.

Note
The CORE Virtual Enclave server remains backward compatible with previous release mobile devices.

D.2.3 Upgrade CORE Virtual Enclave Server software

1. Use rpm to upgrade dymobile package:

rpm -Uvh dymobile-1.2-xxxx.yyyy.RHES.x86_64.rpm

2. Upgrade Unbound.war file by copying it to the appropriate folder in the Tomcat webapps folder:

cp /opt/dyadic-mobile/dyadic-mobile-server.war \
/usr/local/tomcat/webapps/dyadic-mobile-server.war

Note
The updated Unbound Mobile server now supports new Unbound Mobile 1.2 devices, and it is backward compatible with older client devices.

D.2.4 Upgrade Log Mechanism

The Unbound Mobile server logging mechanism was replaced in version 1.2 to use the standard log4j framework. This section describes how to disable the older logging mechanism (versions 1.0/1.1), and how to enable the new logging mechanism.

1. Stop the Tomcat service:

/usr/local/tomcat/bin/shutdown.sh

2. Delete the previous logging mechanism library files:

cd /usr/local/tomcat/bin
rm jul-to-slf4j-1.7.12.jar
rm slf4j-api-1.7.12.jar
rm logback-classic-1.0.6.jar
rm logback-core-1.0.6.jar
rm -rf logback-config

3. Delete the setenv.sh file – only if it was created specifically for the Unbound server (i.e. no additional settings exist in this file).

cd /usr/local/tomcat/bin
rm setenv.sh

4. Edit /usr/local/tomcat/conf/logging.properties, and remove the line:

handlers = org.slf4j.bridge.SLF4JBridgeHandler

5. Edit /usr/local/tomcat/context.xml, and remove the line:

<Loader delegate="true"/>

6. Start Tomcat:

/usr/local/tomcat/bin/startup.sh

D.2.5 Regenerate Server Info

Skip this step if you are planning to perform Enable Client Settings Feature (optional).

Perform the following steps (refer to Installation for more details):

1. Regenerate server-info.txt.
2. Obtain the corresponding signature file.
3. Integrate the signature file into CORE Virtual Enclave software.

D.2.6 Enable Storage Encryption (optional)

To encrypt keys stored in the DB, run the following command:

mobilecl enable-storage-enc

D.2.7 Enable Client Settings Feature (optional)

The Client Settings feature allows specifying attribute-value pairs, such as “refresh interval” that can be fetched and used by a mobile app.

This feature requires using a new key clientSettingsKey that is defined in the release 1.2. To create this key perform the following steps (refer to Installation for more details):

1. Regenerate server-info.txt.
2. Obtain the corresponding signature file.
3. Integrate the signature file into the CORE Virtual Enclave software.

Appendix E. Crypto Algorithms

This section contains the common uses cases for CORE Virtual Enclave and the associated crypto alogorithms.

Use Case	Algorithm
RSA token signing	RSA 2048
EC token signing	ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. P256
Encryption token key exchange	ECDHDiffie–Hellman (ECDH) is a key agreement protocol used to establish shared secret by deriving it from EC keys. P256
Data encryption	AES 256 GCM
Offline HOTP	HMACHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key. –SHA1 (standard HOTP)
Online OTPOne-Time Password (or Pin) - a password that is valid for only one login session or transaction. (HOTP, TOTP)	HMACHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key. – SHA1 (standard HOTP/TOTP)