Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Creating and maintaining a cryptography policy

> The Progress 4GL allows you to establish a consistent set of defaults for handling cryptography in an application using the `SECURITY-POLICY` system handle. These cryptography settings apply globally for the duration of a 4GL session. Table 2–12 lists the attributes that you can read and set for this system handle. These attributes are both readable and setable unless otherwise indicated.

> Table 2–12: SECURITY-POLICY system handle attributes
> Attribute | Description
> --- | ---
>     ENCRYPTION-SALT
> | A `RAW` value used together with a simple password to generate a more random and unique password-based encryption (PBE) key (default: none). For any value that you set, only the first 8 bytes are used, and values with fewer than 8 bytes are padded with zeroes. Note: Typically, you never need to set this value, and then only if the security specification for your application requires it.
>     PBE-HASH-ALGORITHM
> | A `CHARACTER` value that specifies the hashing algorithm to use for generating a PBE key, which you can specify as `"MD5"` or `"SHA-1"` (default: `"SHA-1"`). Note: Typically, you never need to set this value, and then only if the security specification for your application requires it.
>     PBE-KEY-ROUNDS
> | A positive `INTEGER` value that specifies the number of algorithm iterations to use for PBE key generation (default: `1000`). Note: Extremely large values for this setting can significantly degrade performance. Typically, you never need to set this value, and then only if the security specification for your application requires it.
>     SYMMETRIC-ENCRYPTION-ALGORITHM
> | A `CHARACTER` value that specifies a supported algorithm, mode, and key size used by the 4GL symmetric encryption and decryption facilities. It must be one of the comma-separated values from the `SYMMETRIC-SUPPORT` attribute (default: `"AES_CBC_128"`).
>     SYMMETRIC-ENCRYPTION-KEY
> | A write-only `RAW` value that specifies the symmetric key to use for encryption and decryption (default: none).
>     SYMMETRIC-ENCRYPTION-IV
> | A `RAW` value used together with the symmetric encryption key to provide a more random data encryption (default: none). Note: Typically, you never need to set this value, and then only if the security specification for your application requires it.
>     SYMMETRIC-SUPPORT
> | A read-only `CHARACTER` value that contains a comma-separated list of supported values for the `SYMMETRIC-ENCRYPTION-ALGORITHM` attribute setting.

> For information on OpenEdge-supported defaults and options for setting these attributes, see the OpenEdge Development: Progress 4GL Reference .

> Caution: In general, you must manage the values that you set for a cryptography policy in a safe manner, including generation, storage, and transport. Improper management of these values can result in loss of data.

> ##### Setting a symmetric encryption algorithm

> The encryption algorithm setting determines how the 4GL encryption and decryption functions (see the "Implementing symmetric cryptography in the 4GL" section) work to protect data confidentiality in your application. This setting is actually a combination of three elements expressed in the following form:

> Syntax
>     AAA_MMM_n

> These three elements specify:

> ``AAA``

> An alpha or alphanumeric abbreviation for the algorithm.

> ``MMM``

> An alpha abbreviation for the mode to use.

> ``n``

> A numeric value for the key size to use.

> The OpenEdge default setting for the `SYMMETRIC-ENCRYPTION-ALGORITHM` attribute is `"AES_CBC_128"`, which means the AES algorithm in CBC mode using a 128-bit key. The combination of algorithm, mode, and key size determines the strength and speed of the encryption. You can accept the OpenEdge default or choose a different setting, depending on your application requirements. Any setting you choose for the `SYMMETRIC-ENCRYPTION-ALGORITHM` attribute is used by each instance of a 4GL encryption/decryption function unless you specify an override for that function.

> For more information on encryption algorithms, modes, and cryptographic keys, see the sections on cryptography in OpenEdge Getting Started: Core Business Services .

> ##### Setting an encryption key

> You can set the `SYMMETRIC-ENCRYPTION-KEY` attribute to any `RAW`, `MEMPTR`, `CHARACTER`, or `LONGCHAR` value that conforms to the specified key size of your algorithm setting. A `RAW` or `MEMPTR` value specifies a raw binary value for the key. A `CHARACTER` or `LONGCHAR` value creates a PBE, PKC#5-compliant, binary key with a default salt value.

> Caution: Note that the result of setting the `SYMMETRIC-ENCRYPTION-KEY` attribute is unreadable to prevent it against access by memory scanners and debuggers. You must ensure that any source for this value is overwritten in memory, or otherwise protected from unauthorized access.

> The 4GL also provides a number of facilities for generating symmetric keys of various types. For more information, see the "Generating encryption keys" section.

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