Peer Name Verification by the TLS Connector

When server verification or client verification are enabled, peer name verification is also enabled. This is the process of matching names that are specified in the TLS profile against names that are defined in the peer's certificate. As soon as the first name is matched, peer name verification is considered successful.

The certificate itself may specify one or more Common Names, and one or more Subject Alternative Names (SANs), such as

Peer name verification is an important measure in preventing man-in-the-middle attacks, because certificates cannot be used on machines or domains other than the one named in the certificate.

Peer name verification is also prone to failure because a peer may be known by several names in a variety of formats, and the name being checked must exactly match the name in the certificate. For example:

  • DNS names, such asABC0123.mycompany.com
  • IP addresses, such as 123.0.2.34 (IPv4) or FBAC:23:0:1:: (IPv6)
  • A URI, which can provides a name for a given resource in the form of URN or URL. For example: urn:uniface:urouter:10.3.01 or uniface-tls-driver://host.domain.
  • An email address, such as info@mycompany.com

To provide more flexibility in creating certificates for various situations, and to encourage the use of peer name verification in the TLS connector:

  • The TLS connector can be given a list of names to check using the verify_server_name and verify_client_name options. It is possible to specify multiple DNS names and IP addresses, and one email address.
  • Wildcards can be used in DNS names in the certificate or the TLS options.

It is possible to disable peer name verification by setting verify_server_name and verify_client_name to No (or n or 0).

Matching Peer Names

When trying to match a peer name against a name in the certificate, the TLS connector checks the name against the Subject Alternative Names of that type. If any name specified by verify_server_name (or verify_client_name) matches a name in the certificate, the validation succeeds and the connection is established.

For IP addresses, it also checks the Subject Common Name (which is now deprecated) because it has historically been used to specify an IP address instead of a host name.

For URIs, the TLS connector performs a case-insensitive comparison of the whole string against the Subject Alternative Names of type URI. A URI can be a URL (location) or URN (name) of a resource. It must not include commas and semi-colons, which are used as separators in Uniface.

An Email address is checked against the Subject Alternative Names of type Email address, and against the Subject emailAddress.

Default Peer Name

For server verification, the connector can verify the peer name using the default server name, which is the host name specified in the network path of the client assignment file.

If the verify_server_name option is omitted from the TLS client assignment file, the host name specified in the path that uses that particular TLS profile will be used as the peer name to verify against the certificate of the TLS server.

If the hostname in the path is simply a name that requires a DNS lookup, it will be compared as if it is type DNS. If the hostname is an IP address, it will be compared as type IP.

If the path does not contain a host name, the host name in $DEFAULT_NET or $DEFAULT_TCP_HOST is used.

If these settings also do not specify a host name, then the TLS driver will get the host name from the system.

For example, in the following path, the server name is ABC0123.mycompany: 

[PATHS]
$SRV1 TLS:ABC0123.mycompany+13001:Srv1Cert|username|password|SRV1

However, if the certificate only contains the name mycompany.com, the server name verification will fail, so it is better to provide a list of names using the verify_server_name connector option in the client assignment file. This provides more certainty of the name being matched.

For client verification, there is no default name, so you must provide the client names to check using the verify_client_name connector option in the server assignment file.

Wildcards in Peer Names

A DNS name takes the form host.domain, in which the domain may have multiple segments, for example ABC0123.mycompany.com.

In both certificates and TLS connector options, it is possible to replace an entire segment of the name with the asterisk as wildcard. For example, *.mycompany.com matches any host in the mycompany.com domain.

The TLS connector only supports the use of one wildcard for the left-most segment of the DNS name, which is normally the host name, in the verify_client_name and the verify_server_name option. In the certificate you can have wildcards in other segments as well. If both the connector-specified and certificate names use wildcards, then just the parts that are present are matched.

Wildcards cannot be used in IP addresses or email addresses, neither in the certificate nor the assignment file. However, IPv6 addresses that appear different but are equivalent, such as 0::1 and ::1, will match.