Configure the TLS Connector to Use a Pre-Shared Key

When first configuring Uniface to use TLS, it can be useful to start with a pre-shared key because it is very easy to configure. However, it is much less secure than certificate-based public and private keys.

Note: Pre-shared key authentication is not supported for Uniface web applications.

To have the TLS connector use a pre-shared key, you must specify the same pre-shared key for the TLS server and all its clients.

The following steps explain how to configure the Uniface Router-client connection to use TLS on port 13002.

Stop the Uniface Router and all the applications that access it.
For more information, see Stop and Start the Uniface Router.
In the urouter.asn file, set the TLS connector option shared_key in the USYS$TLS_PARAMS setting:
```
;urouter.asn
[DRIVER_SETTINGS]
USYS$TLS_PARAMS shared_key=th1s Is my s*cret pHrase
```
Restart the Uniface Router with the TLS port.
1. On Windows, remove the urouter service and reinstall it using TLS:.
  1. Remove the urouter service using the command line urouter /rem="ServiceName". For example:
```
D:\uniface\common\bin\urouter /rem "Uniface urouter"
```
  2. Reinstall it using the same command line used before, but specify the TLS: port. For example:
```
urouter.exe /inst "Uniface urouter" tls:+13002
```
  For more information, see urouter.
2. On Unix, if you are starting the Uniface Router from the command line or a shell script:
```
urouter tls:+13002
```
Edit the assignment file of the client applications that should communicate with the Uniface Router using TLS.
1. Set the TLS connector option shared_key with the same pre-shared key as the Uniface Router. For example::
```
;client.asn
[DRIVER_SETTINGS]
USYS$TLS_PARAMS shared_key=th1s Is my s*cret pHrase
```
2. Replace TCP: with TLS: in the connection string of all paths that lead to the specific Uniface Router.
  This can include database paths, and the $DEFAULT_NET and $DNP settings. For example:
```
; client.asn
[PATHS]
; path to the Uniface Server for an SQL Lite database:
$DBMS=TLS:ABC_host+13002|user|password|SLESERVER 
```
3. Restart the client application to have the new configuration take effect.

After successful deployment of TLS, the firewall can be configured to block the incoming data to the TCP port of the Uniface Router and only forward incoming data over the newly configured TLS port of the Uniface Router.

Securing the Shared Key

A pre-shared key can potentially be read by a hacker who has gained read access to your assignment files, so you should take precautions to prevent this:

Use Pathscrambler to encrypt the key in your assignment files. For more information, see Pathscrambler and Encrypting Paths and Other Sensitive Data Using PathScrambler.
Restrict read access to the user account under which the Uniface executable runs (for example, uniface for client applications, userver for Uniface Servers, and urouter for Uniface Router).

Certificates provide better protection than pre-shared keys. Once you have TLS working with pre-shared keys, consider whether some TLS connections should use certificate authentication. For more information, see Configure the TLS Connector to Use Certificates.