TLS Connection Profiles

A TLS connection profile is a named collection of TLS connector options that can be used to define multiple connections to Uniface Routers and Uniface Servers, each with its own configuration.

For example, you can define one profile that uses pre-shared key authentication and another profile for certificate-based authentication. This enables a Uniface client to connect to multiple Uniface Servers (via the Uniface Router) using different encryption modes.

Default Connection Profile

A default connection profile can be defined using USYS$TLS_PARAMS in the [DRIVER_SETTINGS] of the assignment file. This default profile can specify either a pre-shared key or certificate-based configuration settings. The default profile is used only when you do not specify a connection profile for a specific connection string. If you specify a connection profile in a connection string, and that profile is not defined, the connection will fail and a network error is returned.

The simplest default profile is for pre-shared key authentication, in which case it must specify the pre-shared key using the shared_key connector option. For example:

; client.asn
[DRIVER_SETTINGS]
USYS$TLS_PARAMS=shared_key=V6rySecret!

This default profile can be used to connect to various Uniface Routers. As long as this client connects to a port that uses the same pre-shared key, regardless of the configuration name that the Uniface Router is using, this single definition will suffice.

Connection Profiles

You can define TLS connection profiles in the [NET_SETTINGS] section of the relevant assignment files, and then use the profile in paths settings and command lines that specify connection strings.

For example, consider a Uniface Router that has two connection profiles defined:

; urouter.asn
 [NET_SETTINGS]
  PSKProfile shared_key=V6rySecret!
  CertProfile verify_server=yes, srv_cert=usys:myserver1.crt, srv_key=usys:myserver1.key

Each client or Uniface Server that connects to this Uniface Router would normally have a corresponding profile defined in its assignment file. Usually, the name of the profile is the same, but the settings must be consistent with each other, meaning that they specify the same type of certification. The specific settings will differ because each side is using a different TLS role—one is a client and one is a server.

For example:

In the following client assignment, the CertProfile profile specifies the settings that match the same profile in the urouter.asn.
```
;client.asn
 [NET_SETTINGS]
 CertProfile verify_server=yes, ca_cert=my_ca_certs.crt
```
In the following Uniface Server assignment file, the PSKProfile profile is exactly the same as in the urouter.asn, because the shared key is the same:
```
;userver.asn
 [NET_SETTINGS]
 PSKProfile shared_key=V6rySecret!
```
A TLS client could also provide the same profile using USYS$TLS_PARAMS (the default profile), but it is often clearer to use the same profile name through-out.

Using Connection Profiles

Once defined, TLS connection profiles can be used in the connection strings used to start Uniface Routers and Servers. They can be used in path definitions, $DEFAULT_NET and $DNP settings, and command lines. For example:

Path definitions in the client assignment file:

[PATHS]
 $TLS1      TLS:host1+13002:PSKProfile|user|pwd
 $TLS2      TLS:host2+13002:CertProfile|user|pwd
 $TLS3      TLS:host3+13002|user|pwd

Note: This last path uses the USYS$TLS_PARAMS because no connection profile is specified.

The command line used to start a Uniface Router or install it as a service on host2.
- If host2 is Unix:
```
urouter TLS:+13002:CertProfile
```
- If host2 is Windows, install it as a service:
```
urouter /inst="Uniface urouter" TLS:+13002:CertProfile
```

The $DEFAULT_NET assignment setting:

[SETTINGS]
$DEFAULT_NET=TLS:host1+13002:PSKProfile|user|pwd

The command line used to start a Uniface Server:
```
userver /dnp=host2:+13002:CertProfile
```

Special Consideration for an Exclusive Server

When a client specifies a path to an exclusive Uniface Server, the connection profile must be honored by both the Uniface Router and the exclusive server. For example

[PATHS]
 $tls_ex	TLS:host1+13002:PSKProfile|user|pwd /ex

The Uniface Router must have been started with at least:

urouter.exe tls:+13002:PSKProfile

When the Uniface Router starts the exclusive server, the UST definition in the [SERVERS] section determines how it registers with the Uniface Router using the /dnp and /altnet switches, but the exclusive server creates a listening port using the same TLS profile name:

tls:host1+[port_number]:PSKProfile

This means that the assignment files of the client, Uniface Router and Uniface Server must define PSKProfile in the [NET_SETTINGS] section in the same way.