Troubleshooting Encrypted Connections

When configuring the use of encrypted connections a number of common errors may occur. In this section a description of these errors is given, along with possible solutions.

The System Administrator may configure the EMu server to accept encrypted connections only. The -s option for texserver will force the server to only accept connections where encryption is enabled. If the EMu client is a version prior to 4.0.03, then encryption is not supported and the following error message is displayed:

TexAPI Error:

Only SSL based communications are supported. (Number -374)

The solution is to upgrade the EMu client to version 4.0.03 or greater.

If the System Administrator has turned on the -s option for texserver, thus forcing encrypted connections, and the server-side certificates (server.crt and server.key) are not installed, the following error message is displayed:

TexAPI Error:

Certificates required for secure communications are not installed. (Number -377)

The solution is to generate the private key (server.key) and public digital certificate (server.crt) and place them in the correct location ($TEXHOME/etc/certs).

The initiation of an encrypted connection involves a handshake between the client and server programs. If an error occurs as part of the handshake, the following message is displayed:

TexAPI Error:

Cannot connect to SSL server(Number 605) at offset 0

There are many reasons why a protocol error may occur. The most common are:

  • The private key file $TEXHOME/etc/certs/server.key cannot be read. The error implies the contents of the private key file are corrupted.
  • The public digital certificate file $TEXHOME/etc/certs/server.crt cannot be read. The error implies the contents of the public certificate file are corrupted.
  • A private key/public certificate mismatch. The public digital key server.crt was not generated using the private key found in server.key. Either the private key or public certificate is incorrect.
  • An acceptable cipher cannot be found. The client and server cannot agree on a cipher to use for the connection encryption. The server ciphers file should be altered to match a client cipher or vice versa.

Server-side debugging may be required to determine the exact cause of the error. The Texpress debug flags s15,16 will output the reason for the protocol error. For details on how to set Texpress debug flags please contact EMu support.

In order for the client to verify the server's certificate the client must have a copy of the server's top level public CA certificate. If the top level certificate is not installed on the client, the following error is displayed:

TexAPI Error:

Cannot verify server certificate (Number 607) at offset 0

The solution is to install the top level CA certificate on the client. The certificate should be placed in a directory called certs located in the same place as the EMu client executable.

The Common Name field of the server's public digital certificate must contain the host name of the EMu server. Wild cards are supported using the asterisk character. If the Common Name field of the server's certificate does not match the host name to which the client is connected, the following error is displayed:

TexAPI Error:

Server hostname does not match with certificate (Number 608) at offset 0

The solution is to fix up your DNS so that the host name of the EMu server matches the host name stored in the server's certificate. If this is not possible, a new server certificate should be generated with the correct host name.