Certificate Verification by the TLS Connector

TLS provides peer verification on a network level through the use of certificates that use public and private keys.

In peer verification, one or both sides of the conversation between TLS client and server want to be sure that they are communicating with a valid peer and not an imposter. They do not immediately trust each other, but they do trust an independent third party, known as the certification authority (CA). The certification authority provides a certificate to the verifier. By accepting and using this certificate, the verifier trusts the certification authority.

The party to be verified has a certificate that says who they are, and has been signed by the certification authority. In signing the certificate, the certification authority vouches for the party that is being verified. The verifier can then examine the signed certificate, and if it is signed by the same certificate that it trusts, it considers the certificate verified.

Typically, a TLS client application will want to be sure that the TLS server application is not being impersonated. For example, in online banking, the client wants to be sure it is communicating with the bank. This is known as server verification. Normally the bank will not wish to verify the client on a network level. The client, once connected, provides application-level verification, such as a username and password. However, in some circumstances, a server may only want to allow clients from certain network locations, in which case it can use client verification.

For both server and client verification, the TLS connector automatically performs peer name verification to check that the name of peer matches the name in its certificate. It is possible to disable peer name verification, or provide a list of names, one of which should match the name in the certificate. For more information, see Peer Name Verification by the TLS Connector.

Server Verification

In a typical Uniface environment, client applications and Uniface Servers verify the certificate of the Uniface Router for authentication.

To enable server verification, set the connector option verify_server=Yes in the assignment files of both sides of the connection.

For server verification, the TLS server needs to have access to the server certificate and its key, and the TLS clients need access to the trusted CA certificate that verified the server certificate. The certificates and keys are specified by the connector options server_certificate, server_key, and ca_certificate (or ca_location if all the CA certificates reside in a trust store).

An exclusive server is both a TLS client and a TLS server, so it will need to use all three options.

Client Verification

If server verification is enabled, it is optionally possible to enable client verification. To do so, set the verify_client=Yes in the assignment files on both sides of the connection.

Client verification is the mirror image of server verification and also requires a set of certificate, key, and trusted CA certificate files. TLS clients provide access to the client certificate and key, and the TLS server provides access to the CA certificate that verifies the client certificate. The certificates and keys are specified by the connector options client_certificate, client_key, and ca_certificate or ca_location.

When client verification is enabled, the verify_client_name option must be specified in the TLS server's assignment file.

Server and Client Verification

In the case of an exclusive server, which is both a TLS client and TLS server that uses both server and client verification, it must provide the CA certificate, possibly different ones, for both verifications. Use the ca_location option to specify the trust store that contains both CA certificates, or use the ca_certificate option to specify a file that contains both CA certificates.

Certificate and Key Files

All certificates and keys must be provided as PEM formatted files. When specifying a certificate file to be verified, the file should only contain one certificate. When specifying the CA certificate file, the file would normally be a collection of all the trusted certificates.

The certificate and the key may be combined into a single file. In the case of self-signed certificates, the certificate and the CA certificate are the same.

Keys for certificates may be password protected. If this is the case, you must supply the corresponding password using the server_key_password and client_key_password options.

All certificate and key files (and their defaults) can be re-directed using the [FILES] section in the assignment file.

Defaults

If a certificate and a key are not specified, default file names and locations are used:

  • The default location for TLS server certificates and key is the USYS directory:

    • ca_certificate = usys:ca-bundle.crt
    • server_certificate = usys:server.crt
    • server_key = usys:server.key

  • The default location for TLS client certificates and key is the current working directory:

    • client_certificate = personal.crt
    • client_key = personal.key

For example, in a TLS server:

;urouter.asn
[NET_SETTINGS]
DefProfile = verify_server=1

Result: The defaults for server_certificate and server_key are used. Both usys:server.crt and usys:server.key must exist, but they may be re-assigned to the same file. If one of them cannot be resolved, an error will be raised.

Specifying Certificates and Keys

  • If either a certificate or key is explicitly specified, both must be specified or it will be seen as an error. For example: 
    ;urouter.asn
[NET_SETTINGS]
Profile1 = verify_server=1, server_certificate = cert.crt, server_key = key.key
; Result: Specifies files are used

Profile2 = verify_server=1, server_certificate = cert.crt
Profile3 = verify_server=1, server_key = key.key
; Result: An error is raised because only one of the certificate/key pair is specified
  • If the certificate or key are in a combined file, both options must specify the same file (or the [FILES ] section of the assignment file must be used to re-assign the default names). For example:
    ;urouter.asn
[NET_SETTINGS]
Profile = verify_server=1,  server_certificate = combined.crt, server_key = combined.crt
; Result: The combined.crt file is used

Related Topics