Using client/server encryption

This topic includes the following:


The xfServer encryption feature enables you to encrypt the transfer of sensitive data across a network. xfServer interfaces with a third‑party library, OpenSSL, to provide SSL support for secure data transport between client and server.

To use encryption, the server and all clients must be version 9.3 or higher. To be able to specify the protocol version (‑scl option), the server and all clients must be version 10.3.1b or higher.

You have the option of using master or slave encryption. When master encryption is enabled, all data packets to and from the server are encrypted. When slave encryption is enabled, data packets on specific channels are encrypted. You can indicate what data should be encrypted with an option on the OPEN statement or by flagging a particular file as requiring encryption. See Specifying the data to encrypt for slave encryption.


Using encryption can affect performance because data must be encrypted and decrypted on both sides of the xfServer connection. The cipher negotiation between client and server, even though it happens only on the first OPEN statement, also takes time.

Although master encryption is inherently more secure, slave encryption affords better performance. As an alternative to slave encryption, you may want to consider having two xfServer services—one that uses master encryption for secure communication and a second one for non‑secure communication.

Whether using master or slave, you can improve performance by using Select statements to read the file on the server and select the records to send to the client; then, only the selected records need to be encrypted and decrypted, rather than the whole file. (See Synergex.SynergyDE.Select.Select for more information on the Select class.) Another way to improve performance is to use xfServerPlus to do processing on the server, and then send only the necessary data to the client. (See the xfNetLink & xfServerPlus User’s Guide.)

To implement encryption, you must start rsynd with the ‑encrypt option (/ENCRYPT on OpenVMS) or by selecting the Enable encryption option in the Synergy Configuration Program on Windows. You also specify a certificate file, the cipher level, and the security compliance level (i.e., protocol). The three cipher options (high, medium, low) map to specific cipher suites and protocols, which vary by OpenSSL version. See Setting up the server and client machines for encryption.  


If you see the error “Cannot load random state”, it means there is not enough random data on the system to seed cryptographic algorithms. To correct this, you must define the SYNSSL_RAND environment variable on either the client or the server (depending on where the error occurred) to point to a file that can be used to gather random data.

Understanding cipher suites and protocols

When enabling encryption for xfServer, you specify a cipher level, which determines which cipher suites will be used, as well as a security compliance level (‑scl option), which defines the protocols to use.

The cipher levels (low, medium, high) map to specific cipher suites, which are grouped into security levels by OpenSSL. These suites and their groupings vary by operating system and OpenSSL version, and they often change as new, more secure ciphers are developed and older ones are found to be vulnerable and are retired. This is why rsynd requires only the level of cipher suite desired rather than a specific suite. (You can see the specific suite and protocol being used; see Verifying that encryption is requested.)

Each cipher suite supports one or more protocols, such as SSLv3 or TLS 1.0. Support for TLS 1.2, which is, as of this writing, the highest protocol available, was added to xfServer in 10.3.1b. xfServer also supports TLS 1.1 and 1.0. As of 10.3.1b, SSLv3 is no longer supported.

Bear in mind that because protocol and cipher support varies by operating system, older systems may not support the newer protocols. For example, Windows Vista and Windows Server 2008 do not support any protocols above TLS 1.0. If you have older clients connecting to xfServer, you will likely need to use level 1 (‑scl=1), which supports TLS 1.0, 1.1, and 1.2, and should work with all clients dating back to version 9.3 (which is when encryption was introduced). Specifying security compliance level 2 (‑scl=2) restricts support to TLS 1.1 and 1.2, which may be required for compliance with certain industry security standards. Setting the security compliance level to zero (‑scl=0) causes rsynd to always use the default security compliance level, whatever it may be. This means the protocols available may change when xfServer is upgraded. (As new threats and vulnerabilities are found, Synergex may need to update the default protocols to maintain a high level of security.) See the ‑scl option in rsynd program for the current default.

You can also specify a security compliance level on the xfServer client with the /scl=level runtime option to the OPEN statement. The scl value on the client should be the same as specified on the server because the client and server must have a cipher suite and protocol in common in order to establish secure communication. By setting an scl value on the client, you can ensure that the server that the client connects to is running at the desired security level. (See the OPTIONS qualifier for more information about using the /scl option with the OPEN statement.)

If the client is unable to negotiate a protocol with the server, the server will close the socket and log an error to the event log (Windows) or rsynd log (UNIX and OpenVMS). On the client, the Synergy Runtime will generate the error “Client server error: host: name” ($ERR_CLNTERR). This error can be generated for any number of reasons; the informational text will tell you the problem. When the problem is an inability to negotiate a protocol, you’ll see “Error requesting secure connection: socket error: an EOF was observed that violates the protocol”.

Specifying the data to encrypt for slave encryption

When xfServer has been started with slave encryption, you can control what data is encrypted in the following ways:

There is also an /scl runtime option for the OPEN statement that can be used to specify the desired protocol.

See the OPTIONS qualifier for more information about /encrypt and /scl.

This is the recommended method because it ensures that any client that accesses that file must use encryption. If you have a file with sensitive data, it is more efficient, as well as more secure, to set the network encryption flag, than to add the /encrypt option to every OPEN statement that opens the file. You can still specify the /scl option if needed on the OPEN statement; if not specified, the default is used.

If a file with the network encryption flag set is referenced with an OPEN statement and encryption has not been enabled on the server, a “File requires network encryption” error ($ERR_NETCRYPT) occurs.


The network encryption flag applies to all remote access from a Synergy application. This means that attempting to access the file via a network path specification (e.g., a mapped drive on Windows) will generate the error $ERR_NETCRYPT. There is no prohibition to accessing the file locally.

For more information about setting the network encryption flag, see the ISAMC routine and isutl ‑p.

Setting up the server and client machines for encryption

Follow these steps to set up your xfServer system to use encryption. For details on which version of OpenSSL is required for your operating system, see OpenSSL requirements. For additional information see Synergex KnowledgeBase article 100001979.

1. Install OpenSSL on your server machine.
2. Ensure that the OpenSSL shared libraries are in the correct location on the server or have been added to the correct path. The library path must be set before registering rsynd on Windows or starting rsynd on UNIX and OpenVMS.
3. Create a certificate file (.pem file). If you name this file rsynd.pem and put it in DBLDIR, it will be used by default when you start rsynd with encryption enabled. However, you may name the file anything you like and put it elsewhere if desired, and then specify it with the ‑cert option (/CERTIFICATE on OpenVMS).

On Windows and OpenVMS, the certificate file cannot include a passphrase. On UNIX, a passphrase is permitted.


See Requesting a certificate for instructions on creating a certificate request file and sending it to a public certificate authority (CA). The CA will then send back a certificate file. You may decide that you do not need a public certificate since xfServer is a proprietary format used on a local server, in which case the generation of a local CA with self‑signed certificates may suffice. See Testing your HTTPS setup locally for steps on how to create the file.

4. Install and configure OpenSSL on the client machines.
5. Start rsynd with the ‑encrypt option (/ENCRYPT on OpenVMS) and specify master encryption if desired. (The default is slave.) Specify a non‑default certificate filename, cipher level, and security compliance level if desired. See rsynd program for detailed syntax and examples.

Or, on Windows, start rsynd from the Synergy Configuration Program and select the Enable encryption option, and then specify the cipher level, certificate file, and security compliance level. See Modifying the SynSrv xfServer service.


If you are running xfServer in non‑secure mode (‑n or /NOSECURE) with encryption enabled, you must specify a default user account (‑u or /DEFAULT_USER).

Verifying that encryption is requested

To verify that a channel is encrypted, use the SLE (Socket Level Encryption) option to the GETFA routine; it returns 1 or 0.

To see the specific cipher and protocol being used, use the SLC (Socket Level Cipher) option to the GETFA routine; it returns a string identifying the cipher and protocol. For example,

AES256-GCM-SHA384    TLSv1.2 Kx=RSA     Au=RSA  Enc=AESGCM(256) Mac=AEAD

If the field argument is not large enough to hold the entire string (which could be up to 128 bytes), it will be truncated. If the channel is not encrypted, a blank string is returned. For more information on the SLE and SLC options, see the GETFA routine.

If you are using file level encryption, you can verify that a file is encrypted with the NETCRYPT request keyword to the %ISINFO function.