Setup for Encrypted Connections

The default installation of the EMu server does not have encrypted connections enabled. The following files need to exist to enable encrypted connections:

  • server.key - EMu server's private key
  • server.crt - EMu server's public digital certificate
  • ciphers - list of ciphers the server will support

These files must be placed in a directory called certs under the Texpress etc directory. For a standard EMu installation this corresponds to:

$EMUHOME/texpress/8.2/etc/certs.

If the files are not found, EMu will not attempt to use encrypted connections.

See How to generate certificates for details on how to create server.key and server.crt.

See How to configure ciphers for details about configuring ciphers.

The permissions on the server.key file should restrict access to read-only by user root. All other permissions should be disabled, that is the file owner should be root and the permissions should be r--------. If these permissions are not set, it is possible that someone may access the file and so compromise the integrity of the system!

As described in Requirements, the EMu server will drop back to an unencrypted connection if versions earlier than 4.0.03 of the EMu client are used. If you want to enforce encrypted connections the -s option should be added to the texserver command configured in inetd/xinetd/svcs.

For example, the following inetd entry will accept encrypted connections only:

emuclient stream tcp nowait root /home/emu/client/bin/emurun emurun texserver -aemu -i -L -t60 -s

The EMu client needs to verify the EMu server's public digital certificate for an encrypted connection to be established. In order to verify the certificate the client must be able to locate a valid CA (Certificate Authority) certificate for the Issuer of the server's certificate. In the case of a certificate chain this must be the Issuer of the first or "root" certificate. There are two locations used to hold CA certificates:

  1. The first is on the EMu server and is used by programs using either TexAPI or texapi.pm (a perl based interface to TexAPI). These programs include web services and IMu.
  2. The second is on the EMu client's machine and is used by the Windows client.

CA certificates stored on the EMu server must be placed in the $EMUPATH/etc/certs directory. The certificates should be stored in files with a .crt extension. CA bundles are also supported. A bundle is simply the concatenation of a number of certificates into one file. An optional ciphers file may also exist in the certificates directory. If it exists, it should list the ciphers the EMu client is willing to support.

See Configuring ciphers for details about configuring ciphers.

CA certificates required by the EMu Windows client should be stored in the certs directory under the location where the EMu executable is installed. As with CA certificates stored on the EMu server, the files must have a .crt extension and CA bundles are supported. A ciphers file may also be supplied defining the ciphers the client is willing to use.

As with the EMu client, TexJDBC needs to be able to verify the EMu server's public digital certificate. The required CA certificates must be stored in an accessible Java Key Store (JKS). The system key store is located at $JAVA_HOME/jre/lib/security/cacerts. A key store may have a password associated with it. The password allows the integrity of the stored certificates to be checked when they are accessed. The password is not required to access the key store. The location of the key store used may be altered by setting the following system properties:

javax.net.ssl.trustStore

The location of the Java Key Store file containing the CA certificates to use for verifying the server's certificate.

javax.net.ssl.trustStorePassword

The password to use to check the integrity of the Java Key Store.

For example, if you want to use a key store located at /home/emu/etc/certs/cacerts with a password of emustore, you could invoke java using:

java -Djavax.net.ssl.trustStore=/home/emu/etc/certs/cacerts -Djavax.net.ssl.trustStorePassword=emustore -jar application.jar

The location and password of the key store may also be specified using the trustStore and trustStorePassword connection properties:

Properties props = new Properties(); 
props.setProperty("trustStore", "/home/emu/etc/certs/cacerts"); 
props.setProperty("trustStorePassword", "emustore"); 
... 
Connection conn = DriverManager.getConnection("jdbc:texpress:socket", props);

The keytool command should be used to import a CA certificate into a java key store:

keytool -importcert -alias alias -file certfile -storetype JKS -keystore keystore

where:

alias

is an arbitrary unique name used to define the certificate within the key store.

certfile

is the file containing the CA certificate.

keystore

is the location of the key store file into which the certificate is imported.

If keystore does not exist, a new key store is created. You will be prompted for the password if the key store already exists, otherwise you will be asked to set the password for the key store created.

To list the certificates in a key store use:

keytool -list -v -keystore keystore

where keystore is the location of the key store file.