TinyTERM Enterprise TE Server 2.0.0 - Linux README
Copyright (c) 2019 - 2020 Century Software. All rights reserved.

=============================================================================

Contents:

1. Introduction
2. Installation/Upgrade
3. Configuration
4. Activation
5. Client Configuration
6. Generating CSR (Certificate Signing Request) and X.509 Certificate
7. Uninstallation

=============================================================================

1. Introduction
---------------

This guide will explain how to install and run TinyTERM Enterprise TE Server
(otherwise known as HostTE or HTE) as a proxy for the Century Software License
Server (LCS service).

Using the license proxy can allow for more detailed tracking of clients by
optionally forwarding the private IP addresses of devices behind a firewall.

The proxy may also be used as a means to provide access to the license server
in environments where the ability to make outgoing connections is limited,
as long as the server is hosted on a machine that can make outgoing connections
to Century's license server; e.g., a machine in front of a corporate firewall.

Notes:

* In this document, "client" usually refers to a device running TinyTERM
Enterprise, but could also refer to other types of clients, such as a web
browser. In the latter case the client will be referred to as a browser, or
it should otherwise be clear from context which type of client is being
referred to.

* In order to take advantage of the tracking feature, there must not be a
router which performs NAT (Network Address Translation) between the client
and the proxy (provided that clients connected through the router need to be
tracked individually and not appear as a single device to the proxy), but
the proxy server itself can, and is expected to be, hosted behind a
router/gateway performing NAT.

* TinyTERM Enterprise TE Server requires IPv4

* Currently the proxy server must be run as a privileged user, but it's
possible that in an upcoming release a feature will be added to run in a less
privileged mode after startup. Running the server in a chroot jail is another
possible security enhancment. Want to know more? Contact Century Software
technical support at support@censoft.com for more information.

2. Installation
---------------

The proxy server can easily be installed with an RPM package. Several Linux
distributions support this package type, including RHEL (Red Hat Enterprise
Linux), SUSE Enterprise Linux, Fedora, and CentOS. This package is intended
to be installed on systems that manage services with systemd.

To install the package, run the following command (root access required):

sudo rpm -i <package_name> (e.g. hte-2.0.0-1.x86_64.rpm)

The following files and directories will be created:

/usr/bin/cenproxy
/etc/hte
/etc/systemd/system/cenproxy.service
/var/hte
/var/log/hte

If instead you want to upgrade the install from a newer package:

rpm -U <package_name>

To verify that the package is installed correctly, run the command:

rpm -q hte

You can now verify that the service can be started with systemctl:

systemctl status cenproxy

You should see output that says the service exists but is not running or
enabled.

Note: It's recommended to follow the steps listed in section 3
(Configuration) and then proceed to start/enable the service.

You can start the service in the normal way:

systemctl start cenproxy

To enable the service to run at system start:

systemctl enable cenproxy

You will now want to configure the server and then restart it with the command:

systemctl restart cenproxy

Note:

Alternatively, a compressed tarball archive can be provided. The server can then be
run directly from the extracted folder or a custom install. The steps to do this are
not covered in this file, but you can run the main executable (cenproxy) with the -h
option to see a list of supported options. (Note that the hte_config.json and the
certs folder must be located in the same directory, and the path to this folder can
be set with the -config-dir option. All the other files must be located in a location
set with the -root-dir, and the folder for log files set with -log-dir).

3. Configuration
----------------

The first step is to configure SSL/TLS, which is required in order for the proxy
to work. To do this, you need to have an X.509 certificate and the corresponding
private key, both must be PEM encoded and have a .pem extension, and the private
key must be unencrypted.

If you don't currently have a certificate and private key, see section 7
(Generating A Certificate Signing Request). If you wish to host using a
self-signed certificate, see section 8 (Creating a self-signed certificate), which
leaves off where section 7 ends with the steps to sign your own certificate with
your private key. For self-signed certificates, in order for TinyTERM Enterprise
to validate the proxy server's identity, you will have to import the certificate
file. In some cases this can be done with with a MDM (Mobile Device Management)
system, such as Airwatch. It's also possible to import the certificate with a
.ttconfig file (see section 5 "Client Configuration")

1) Make sure the certificate and private key are named correctly, e.g. cert.pem
and key.pem.

2) Next copy the certificate/private-key into /etc/hte/certs. You might want
to make sure the permissions are set to prevent users other than the user
the server is run as from accessing the file; e.g.,

sudo chown root:root /etc/hte/cert.pem /etc/hte/key.pem
sudo chmod 0660 /etc/hte/cert.pem /etc/hte/key.pem

3) Edit the configuration file /etc/hte/hte_config.json. The following
settings should be added:

{
	"cert": "cert",             # name of your certificate without extension
	"pkey": "key",              # name of your private key without extension
	"sslEnabled": true,
	"port": "443",              # port to listen on for connections, default 443
	"lcsProxy": true,           # Enable the license proxy feature
	"forwardAddresses": true    # Optionally enable for tracking
}

Note the following:

*) Ensure that the last element of the above dictionary is not followed by a
delimiting comma

*) The pound sign comments are just for clarification and are not supported by
the file format. They should be removed for actual use.

*) Key names are case-sensitive.

This marks the end of the required configuration. You can follow the steps at
the end of section 2 in order to enable and start the service, and then continue
to section 4 "Activation".

If you're experiencing problems starting the server or if there is an execution
fault under some condition, verbose logging can be enabled with a command line
option:

1) Edit /etc/systemd/system/cenproxy.service
2) Under the Service section add the option "-debugmask all" at the end of the
command following ExecStart=
3) Start or restart the service

If you want to see a full list of command line options, run the command:

cenproxy -h -config-dir /etc/hte -root-dir /var/hte -log-dir /var/log/hte

4. Activation
-------------

After installing the proxy server on a new machine and starting the service,
you will be able to access the server using a web browser. However, if the
server is hosted from a machine with a firewall, make sure the correct port is
open in the firewall settings of that machine.

If SSL is enabled, use the https scheme in the url, otherwise use http. You will
be able to activate the server without SSL enabled, but the server will not
proxy requests in that state.

If you configured the service to listen on a port other than the default for
the configured protocol (80 for http and 443 for https), then don't forget to
specify the port in the URL when connecting to the server, e.g.:
https://serverdomain:4433

Once you connect you will be redirected to a license page with instructions.
Simply enter the license information provided by Century Software. If successful, you
will see a page indicating that proxying is enabled and active, or an
error reporting that SSL is not enabled.

5. Client configuration
-----------------------

The first step is to configure the client to connect to the proxy when
performing licensing requests. This is done by updating an internally
stored URL to the following:

https://address_of_your_server/lcs_proxy

Additionally, if you're hosting using a self-signed certificate, then you will
need to add the certificate to the client.

Two major ways of updating device settings are detailed below: using an MDM, or
importing a TinyTERM configuration file, which may be helpful for testing
purposes even if you plan to deploy using your MDM.

5.2 Updating client settings through managed settings (iOS Only):
-----------------------------------------------------------------

If your MDM supports Apple managed settings, add the following key for
TinyTERM Enterprise:

remoteConfigURL https://domain_of_your_server/lcs_proxy

If you can add a certificate to the root CA list across your managed devices,
you can add a self-signed certificate this way. You should be able to use the
web browser on the device to navigate to the proxy server without seeing a
security exception.

Note: The above needs to be tested but should work.

5.3 Updating client settings by importing a TinyTERM configuration
------------------------------------------------------------------

The following instructions apply for TinyTERM Enterprise for iOS:

*) Under the "Global Options" menu item, select "Export Configuration".

*) Uncheck the "Encrypt Export Data" option and choose the desired import
settings.

*) Select "Begin Export" and choose the desired method to transfer the
configuration.

*) Once you have the "TinyTERMConfig.ttconfig", unzip the contents of this
file into an empty folder, and then delete the config, e.g.:

unzip TinyTERMConfig.ttconfig
rm TinyTERMConfig.ttconfig

*) Edit the Preferences.ttsettings file with any text editor. This file is an
XML file conforming with Apple's plist (property list) document type. Add the
following entry to the parent dictionary, and save:

<key>com.censoft.remoteConfigURL</key>
<string>https://address_of_your_server/lcs_proxy</string>

*) If you want to import a certificate, create a file called ib_cacerts.pem and
add any certificates you want to add as root CA's. This is normally the
certificate you used to configure the proxy server if you are hosting with a
self-signed certificate. Note these must be X.509 certificates that are PEM
encoded and contain the BEGIN CERTIFICATE and END CERTIFICATE lines.Only
the certificate should be added and not the private key, which should be
isolated to only secure locations. Importing certificates this way requires
versions of TinyTERM Enterprise after 3.4.5

*) Repackage the contents:

zip TinyTERM.ttconfig *

Be sure to zip the files, not the containing folder. Any file name may be used,
as long as the .ttconfig extension is preserved.

*) Finally, import the new TinyTERM.ttconfig on the iOS client. Transfer of the
configuration can be done with email, Airdrop, iCloud, and other means of
sharing files with iOS devices.

5.4 Test communication with the proxy
-------------------------------------

Once you have configured your client(s), in TinyTERM navigate to the
"Configuration Server" screen under "Global Options". From there, select either
"Synchronize with Config Server" or "Enter Configuration Key". You should get
normal responses back, and if you look in the proxy server logs, you should see
corresponding entries for each request. 

Otherwise, there are several items to troubleshoot:

*) Double check that the proxy server is running and can be reached; make sure a
firewall is not blocking connections.

*) Make sure that the proxy server is activated; i.e., that a license key has
been entered (see section 4).

*) Make sure the proxy server is able to make outgoing connections to
censoft.com.

*) Check /var/log/hte/hte.log, making sure that no errors are being reported and
that (SSL Enabled) is being output after starting the server.

*) If requests for /lcs_proxy are showing up in the server logs, ensure that
they have a HTTP status code of 200

*) Inspect the server certifcate by navigating to the proxy with the browser, or
using the "openssl s_client" utility, make sure this is the same certificate that
you imported in the ib_cacerts.pem file (self-signed certificates only).

*) Double check for typos in file names or keys, making sure the remoteConfigURL
is set correctly.

*) Try enabling verbose logging on the server (see section 3). Note this can
result in log output that is harder to interpret. It may be helpful
to contact support@censoft.com for further troubleshooting. In that case,
please attach the log file to the email.

6. Generating CSR (Certificate Signing Request) and X.509 Certificate
---------------------------------------------------------------------

This section covers using OpenSSL to generate a CSR for an RSA certificate that
can either be sent to a CA to be signed or be used to generate a self-signed
certificate.

Important Note:

If you're signing your own certificates, it may be beneficial to create a
private certificate authority, and to use the private key associated with
your CA certificate to sign server certificates. Using this model can make
it easier to distribute multiple certificates, and more closely mirrors the
way SSL certificates are distributed for use on the internet. For more
information about this, see:

https://www.feistyduck.com/books/bulletproof-ssl-and-tls/ 

6.1 Certificate Requirements
----------------------------

The certificate must meet the requirements as specified by Apple:

*) Certificates using RSA must use keys sizes greater than or equal to 2048 bits
*) Certificates must have a Subject Alt Name extension with the DNS/IP name of
the host
*) Certificates must have a Extended Key Usage extension containing the
serverAuth OID (see below)
*) Certificates must have a validity period no greater than 825 days

The full set of requirements can be found here:

https://support.apple.com/en-us/HT210176

6.2 Generate CSR
----------------

First, generate a private key. The following command will create a 2048 bit
RSA key and prompt for a passphrase to encrypt the key using AES 256-bit
encryption:

openssl genrsa -aes256 -out key_protected.pem 2048

The private key should be protected and stored unencrypted in as few locations as
possible.

Next, we generate a CSR. By default, this command will interactively prompt for
info fields that will be part of the issued certificate. Enter a '.' character
into a field to leave it blank.

openssl req -new -out site_name.csr -key key_protected.pem

The above CSR can be sent to a Certificate Authority to be signed. However, make
sure the certificate you will be receiving will meet the requirements listed in
section 6.1.

6.3 Generating a self-signed certificate
----------------------------------------

If you prefer to use a self-signed certificate, first create an extensions file
with the following contents:

subjectAltName = DNS:example.com, DNS:www.example.com, IP:192.168.0.5
extendedKeyUsage = serverAuth

See the following link for more informations about X.509 extensions:
https://www.openssl.org/docs/manmaster/man5/x509v3_config.html

Next, we issue the command to generate a X.509 certificate and sign it using our
private key:

openssl x509 -req -in site_name.csr -extfile extensions.txt -days 825 -signkey \
key_protected.pem -out cert.pem

The certificate generated from the above command should be put on the server and
can also be added to the client with a configuration import (TinyTERM Enterprise
versions after 3.4.5); to import the certificate onto the iOS system either
through Airdrop, email, or using your MDM, then first generate an identical
certificate but without extensions:

openssl x509 -req -in site_name.csr -days 825 -signkey key_protected.pem -out cert.pem

6.4 Setting up the server
-------------------------

First, decrypt the private key. It's recommended to do this after copying the
key to the /etc/hte/certs folder. Run the following command, you will of course
be prompted for the passphrase:

openssl rsa -in key_protected.pem -out key.pem

Once both the cert.pem and key.pem files are in the /etc/hte/certs folder,
follow the instructions in section 3 ("Configuration").

7. Uninstallation
-----------------

Make sure an hte package is installed:

rpm -q hte

You can remove the package with the erase command, for example:

rpm -e hte-2.0.0-112.x86_64

The above files will not delete configuration and log files created at runtime
or added by the system administrator. If you wish to get rid of all files
related to hte, delete the following folders:

rm -r /etc/hte
rm -r /var/log/hte
