Data encryption


This topic discusses the encryption of data at the application level. For information about encrypting data transferred over a network, see the bulleted links on Data Security and Encryption.

Synergy DBL enables you to encrypt and decrypt sensitive data using industry standard cipher techniques. This is accomplished on an on-demand basis using a set of Synergy subroutines that encrypt and decrypt a specified data region. You determine which data is encrypted as well as how it is encrypted.

The Synergy data encryption feature interfaces with a third-party library, OpenSSL. We use PKCS #5 (Password-Based Cryptography Specification) in conjunction with PBKDF2 key derivation function (an ISO standard) provided by OpenSSL. To learn more about PKCS, visit

Setting up your system for encryption

Follow these steps to set up your system to use encryption.

1. Install OpenSSL. For details on which version of OpenSSL is required for your operating system and where to get it, see OpenSSL requirements.
2. Ensure that the OpenSSL shared libraries are in the correct location or have been added to the correct path.

Encrypting and decrypting data

The DATA_ENCRYPT and DATA_DECRYPT routines encrypt and decrypt data using the data and password buffers that you pass to them. Optionally and recommended, the salt and IV arguments can be used to further enhance security. You can use the DATA_SALTIV routine to generate pseudorandom values that are appropriate for use.


As with the password, the same salt and IV (initialization vector) used to encrypt the data is required to decrypt it, so these values must be saved off. However, the salt and IV don’t need to be kept secret.

The salt is used to derive the encryption key from the password, whereas the IV is used to randomize the resulting encrypted data. The encryption key used to encrypt/decrypt the data is immediately discarded by OpenSSL. Changing the keys that are used can be accomplished by altering either the password or the salt before encrypting. Additional key derivation parameters (iteration and key length) are kept internal and are set appropriately for the requested encryption algorithm. Supported encryption routines include 3DES-CBC (Triple DES) and AES-CBC.

Ciphers process data in blocks. If the length of the data isn’t a multiple of the cipher block size, DATA_ENCRYPT and DATA_DECRYPT use PKCS padding to pad it. Bytes of padding (between 1 byte and the number of bytes in a cipher block) are always added to the data when it is encrypted and then removed when it is decrypted. When using PKCS padding, the unencrypted data can be any size, but the encrypted data is always a multiple of cipher block size; PKCS padding does not allow in-place encryption even when the data is a multiple of the cipher block size.

To encrypt and decrypt data without changing its size (or for in-place encryption), you can suppress padding, but the data must be a multiple of cipher block size. To suppress padding, pass a 0 value to the DATA_ENCRYPT and DATA_DECRYPT routine’s pad argument. If you suppress padding to encrypt a piece of data, you must also suppress padding when you decrypt the same piece of data, or the decryption will fail with an “Argument specified with wrong size” error ($ERR_ARGSIZ).


In-place encryption is not allowed unless you explicitly suppress padding.

Cipher block sizes are as follows:


8 bytes


16 bytes

You can determine the size of the encrypted data by passing the len argument to DATA_ENCRYPT with no destination argument, which applies the following formulas. (Padding is either 1 or 0.)


8 * (%TRUNC(data_size / 8) + padding)


16 * (%TRUNC(data_size / 16) + padding)


Index data should be encrypted only if it is used for lookup only (READ with MATCH:Q_EQ) and not for index sequences (READS) and made into an alpha field of the size of the encrypted region. The key used for the lookup would be encrypted on the client first before passing to a READ or FIND statement. Any file that uses encryption contains binary data and can only be unloaded/reloaded from a counted file.

Access to encrypted data in a Synergy file is not supported by xfODBC. Make sure you mark encrypted fields as “Excluded by ReportWriter” in the repository.

To implement Synergy data encryption,

1. Decide what type of encryption you want to use and which fields should be encrypted. For example, you might choose to use AES-128 encryption to encrypt a field in your customer master record. You can allow for padding by inserting a “pad” field directly after the field and then declaring an overlay field to encompass both the original field and the pad field. Make sure when encrypting that the source doesn’t include the pad field. If the field is a multiple of the cipher block size, you may also suppress padding.
2. If you want to maximize the effectiveness of the cipher by including a random salt and/or IV, call the DATA_SALTIV routine and save the resulting value(s).
3. Before writing data to your master file using the STORE and WRITE statements, call the DATA_ENCRYPT routine with a user password and the salt and/or IV you generated in step 2, if applicable.
4. After reading data from your master file using the READ and READS statements, call the DATA_DECRYPT routine with the same user password, salt, and/or IV that you used to encrypt the data.
5. Convert your master file (if one existed before) to the new record structure. (Note that you must construct a program or routine to perform this conversion; no utility exists to convert the file automatically.)

For an example of a traditional Synergy application that uses the DATA_ENCRYPT and DATA_DECRYPT routines see

For a UI Toolkit application that uses data encryption, see in Synergy CodeExchange.

Data at rest encryption

Synergy allows you to perform data at rest encryption for protected data (for example, credit card, Social Security, NHI, and bank account numbers) as long as you have the following:

For ISAM files, key data encryption is possible where the keys provide direct keyed access (rather than ordered retrieval). Keep the following rules in mind when using data at rest encryption: