Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Managing and transporting crypto data

> Crypto data consists of all the information required to maintain secure data. This includes the source data, typically in clear-text form; the encrypted or hashed data; all passwords, key values, and algorithms; and all platform parameters required to maintain the data, such as code pages for character strings and the byte endian order for binary values.

> This section describes some of the basic objectives and requirements for managing crypto data in the 4GL. For more information on the larger and more complex factors that you need to consider when using cryptography, see the Security whitepaper prepared by Progress Marketing, which can be found on the PSDN Web site.

> Caution: Managing crypto data incorrectly can result in the loss of your original source data. You must ensure that all interactions with this data are both safe and secure.

> ##### Objectives for crypto data management

> The main objectives for managing and transporting crypto data is the same for all types of encryption and data:

> - To ensure that the required level of security is maintained as data is moved and stored.

> - To ensure that secured data can always be recovered by those who are authorized to recover it.

> ##### Requirements for crypto data management

> The requirements for managing and transporting crypto data depend upon the:

> - Type of cryptography — In the 4GL, this can include symmetric cryptography, message digests, and key generation.

> - Media for storage or transport — This can include static media, such as databases and external files and dynamic media, such as session memory and network connections.

> One general requirement for managing encrypted or digested data is to be certain that all keys once generated, are recoverable. For example, if you use the `GENERATE-RANDOM-KEY` function to set a symmetric key and you use this function to directly set the `SYMMETRIC-ENCRYPTION-KEY` attribute of the `SECURITY-POLICY` system handle, the key value that you set is non-recoverable because the `SYMMETRIC-ENCRYPTION-KEY` attribute is write-only. If you encrypt data using this setting, you can never decrypt it after the 4GL session in which you encrypt the data has ended. Therefore, to correctly use the `GENERATE-RANDOM-KEY` function for symmetric encryption, you must set and maintain the value of a readable variable using this function and then set the `SYMMETRIC-ENCRYPTION-KEY` attribute using this variable. Of course, you must also ensure that you immediately save the key value in a secure location and erase the value in memory in order to both secure your current 4GL session and safely recover the key value at a later time to decrypt whatever data you have encrypted with it.

> ##### Crypto data storage

> If you use external files to store crypto keys, passwords, and data make certain that you use secure operating system files to do it.

> If you use a database to store crypto data, be sure to secure any keys or passwords that you store in the database separately from the data that you have encrypted.

> Caution: Never encrypt a password required to access encrypted data using the same password-based encryption (PBE) key used to encrypt the data. Always manage the password separately from the data that you intend to encrypt with it, and always manage the password separately from any salt that you combine with the password to generate the PBE key.

> ##### Crypto data management and transport

> When you store or transport crypto data, you can do it in two basic forms:

> - Binary byte stream — Accessible through a 4GL `MEMPTR` or `RAW` variable. This the native form in which key values and encrypted or hashed data are generated. The primary requirement for binary data is that you maintain byte-endian order for all hardware platforms where you transport the data. You can help to ensure this by using the `GET-BYTE` and `PUT-BYTE` functions to read and write the data instead of `GET-LONG` and `PUT-LONG`. You can also convert a binary data string into a string of hexadecimal character pairs using the 4GL built-in `HEX-ENCODE` function, transport it to a different hardware platform, and convert hexadecimal character string back to binary on that platform using the 4GL built-in `HEX-DECODE` function.

> - Base64-encoded character string — Accessible through a 4GL `CHARACTER` or `LONGCHAR` variable. You can convert binary data into this form using the 4GL built-in `BASE64-ENCODE` function and convert it back to binary using the 4GL built-in `BASE64-DECODE` function. The primary requirement for Base64-encoded and encrypted data is that you remember to decode it from Base64 before you decrypt the data.

> Caution: If encrypted data is not in the correct byte order or format, the `DECRYPT` function has no way of knowing this and will successfully “decrypt” the data to an invalid value.

> If you store encrypted data in a database:

> - Do not use it for searches or indexes unless duplicates are allowed, as there is no way to know that two different pieces of data have been encrypted to the same value.

> - Plan for changes in the size of database items that you store in both clear text and encrypted form. Both encryption and Base64-encoding increase the size of stored data.

> Caution: If you encrypt data in a database, other applications that use the database, such as Crystal Reports, might not work as you want.

> ##### Planning for changes in size for encrypted data

> Data size increases at two points:

> - During symmetric encryption, using the 4GL `ENCRYPT` function.

> - During conversion from a binary byte stream to a Base64-encoded string, using the 4GL `BASE64-ENCODE` function.

> The formula for change in data size during symmetric encryption is:

>     ems = (((ums / 8) + 1) * 8)

> In this formula:

> - `ems` is the encrypted maximum size.

> - `ums` is the unencrypted maximum size.

> The formula for change in data size when Base64-encoding a binary byte stream is:

>     ems = (((bms / 8) + 1) * 8)

> - `ems` is the Base64-encoded maximum size.

> - `bms` is the binary maximum size, which is equal to the encrypted maximum size of the data that has been encrypted using the `DECRYPT` function.

> This increase in size from binary to Base64-encoding is generally 33%. So, encrypted data in a `RAW` or `MEMPTR` variable becomes 33% larger after you convert to a Base64-encoded `CHARACTER` or `LONGCHAR` variable.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095