How secure is your encrypted data? It depends on the security of your keys. Where are they stored? Are they encrypted? Is access controlled? How do you back them up?

In V5R3, i5/OS shipped with a new set of cryptographic APIs that provide data confidentiality and authentication functions. (These APIs are documented in the iSeries Information Center — www.iseries.ibm.com/infocenter — under Programming|APIs|APIs by category|Cryptographic Services.) In addition, key-generation APIs let you generate random key values for both symmetric and asymmetric algorithms. However, V5R3 provides no key management. Figuring out how to store and manage cryptographic keys is completely the V5R3 application programmer's responsibility.

In V5R4, Cryptographic Services adds new functionality to help with key management. New APIs support a hierarchical key store. In addition, existing APIs are enhanced to let you specify new key formats, namely PEM keys, PKCS #5 keys, keys from the Certificate Store, and keys from the new Cryptographic Services Key Store.

Cryptographic Services Key Store

Figure 1 shows a diagram of a hierarchical key system, a commonly used key management technique. At the top of the hierarchy is a master key (or keys). The master key is the only clear key value and must be stored securely. You use key-encrypting keys (KEKs) to encrypt other keys. Typically, you use a KEK to encrypt a key sent to another system or stored outside the key store. KEKs are usually stored encrypted under a master key. Data keys are used directly on user data (e.g., to encrypt or sign). You can encrypt a data key under a KEK or under a master key. i5/OS Cryptographic Services implements such a key hierarchy via a two-tier key store.

Master keys. i5/OS supports eight master keys. Master keys are used to encrypt other keys (i.e., KEKs and data keys), but not data. The master keys are stored in the i5/OS Licensed Internal Code (LIC) in an area that cannot be displayed or dumped. You can access the master keys only with the Cryptographic Services APIs. (For more information about Cryptographic Services master keys, refer to the Information Center article listed in Find Out More, below.) To reference master keys, you simply use a number, 1—8.

To load and set (or activate) a master key, you use APIs. The Load Master Key API takes a passphrase as input. You can load as many passphrases as desired before setting a master key. In fact, to ensure that no single individual has the ability to reproduce a master key, you should assign passphrases to several people.

The Set Master Key API activates the new master key value, which consists of the passphrases previously loaded. The API returns a key verification value (KVV). You should retain this value so that at a later date you can determine whether the master key has been changed.

A key hierarchy is a popular key management technique primarily because it reduces the number of secrets (e.g., plaintext keys and passwords) to protect. Be discriminating about how many master keys you actually need to use and must therefore manage.

Key store files. You can securely store KEKs and data keys in a Cryptographic Services key store file. A key store file is a database file that you create with the Create Key Store API. You specify the file name and library, the public authority, and the master key that encrypts all the key values stored in the key store file. (For more information about Cryptographic Services key store files, refer to the Information Center article listed in Find Out More.)

To store a key in a key store file, use the Write Key Record API. Parameters let you specify the type and size of key; whether the input key value is a binary string, a BER-encoded string, or a Privacy Enhanced Mail (PEM) certificate; whether the input key value is encrypted, and if so, the KEK information; and a label for referencing the key. Or you can use the Generate Key Record API to generate and store a random key value in a key store file, again specifying key type and size and a label for the key record.

To use a key from the key store, you use a new structure defined for the Key Description parameter. This parameter is used by many of the Cryptographic Services APIs (e.g., the Encrypt Data API) for specifying the key data. In this new structure, you specify the key store file name, the library, and the key record label. Cryptographic Services retrieves the key value from the key store file and decrypts it from under the master key before executing the operation (e.g., encrypting data).

When creating key store files, give careful consideration to authorities. Even though key values in a key store file are encrypted, anyone with access to the key store file and the appropriate API (e.g., the Decrypt Data API) could hack the data. Note, however, that a key store file moved to another system is useless if the master key under which it was encrypted has not been set identically.

Master Key Encrypted Keys

As I said, key values in a key store file are encrypted under a master key. You can also encrypt under a master key keys outside of a key store. On the Generate Symmetric Key API and the Generate PKA Key Pair API, you can request that the generated key value be returned encrypted under a master key. Or use the Import Key API to encrypt a clear key value or translate (i.e., decrypt, then encrypt) an encrypted key value under a master key. Again, you must carefully control access to master key encrypted keys.

Changing master key values. Periodically, you should change master key values. All keys encrypted under the master key must then be translated under the newly activated master key value. If you neglect to do this, key values, as well as all data encrypted under them, might be lost.

You use the Translate Key Store API to translate key store files from an old master key value to an active master key value. To translate a master key encrypted key located outside of key store, first use the Export Key API, then use the Import Key API.

Master key encrypted keys not translated after the master key is changed might still be usable if you know the old master key's KVV. When a key is added to a key store file, the KVV of the master key (under which the new key value is encrypted) is stored in the key record. When the key is used on a Cryptographic Services API, the API retrieves the KVV from the key record and compares it with the active and old master key KVVs. However, for master key encrypted keys outside of key store, you must manage the master key KVV and supply it to any APIs yourself. By supplying a KVV, an API can detect when a key is encrypted under an old master key value. The API executes as usual but returns a warning message specifying that you should translate the key. If the key is not translated and the master key value is changed again, the key value is lost, and you cannot recover it unless you restore the original value of the master key.

Master key variants. You can limit the use of a master key encrypted key by using master key variants. For example, if your application program uses a key from the key store to encrypt sensitive data, you can use variants to ensure that the key cannot be used to decrypt the data.

A master key variant is a value that is "XOR'd" (i.e., inserted via an XOR operation) into the master key value before encrypting a key. You specify a master key variant on an API (e.g., the Generate Key Record API) via the Disallowed Function parameter or field. Functions that you can disallow are encrypt, decrypt, Message Authentication Code (MAC and Hash MAC), sign, or any combination of these.

When a key that has been encrypted under a master key variant is used on an operation (e.g., decrypting data), the variant must be supplied to properly decrypt the key. The master key variant for a key store file key is stored in the key record and picked up automatically when that key is specified on an API. For keys outside of the key store, you must manage and supply the master key variant yourself.

If the supplied variant indicates that the operation is disallowed, an error is returned. If the variant is altered to force the operation, the results will be bad. For example, if you use an altered variant on the Decrypt Data API, the decryption proceeds as usual, but the result isn't cleartext data.

Migrating Keys to Another System

To move a master key encrypted key (in or outside of key store) to another system, use the Export Key API. The Export Key API translates the key from encryption under the master key to encryption under a KEK. On the target system, you can then use the Write Key Record API to move the migrated key into the key store, or you can use the Import Key API to translate the key value to encryption under a master key. All these APIs require that the KEK information be specified via algorithm and key contexts. For information about algorithm and key contexts, see "Cryptographic Services APIs: A Tutorial" and the iSeries Information Center documentation, both of which are listed in Find Out More.

The Export Key API is shipped with public authority *EXCLUDE. Be very careful about the access you give to the Export Key API. Anyone with access to master key encrypted keys and the Export Key API can obtain the clear key values.

In general, you should not share master keys with another system. Each system should have unique master keys. However, to move an entire key store file from one system to another without exposing clear key values, you need to set up identical master key values on both systems. To avoid exposing your master key value(s), set up a temporary master key on both systems by loading and setting an unused master key with identical passphrases. On the source system, create a duplicate of the key store file (e.g., using the CRTDUPOBJ CL command). Then translate the duplicated key store file to the temporary master key. After moving the key store file to the target system, translate the key store file to another master key.

Generating Keys

Having good random key values is extremely important. You can obtain good randomness by flipping a coin for each bit of a key value — but a more practical means is to have the computer do this for you.

A computer function that generates a random value is called a pseudorandom number generator (PRNG). (The term "pseudo" is used because generally this function does not directly output from a real random source.) Many PRNGs exist; however, not all are cryptographically strong. "Cryptographically strong" means that the PRNG uses cryptographic functions to ensure that the output is unpredictably random. This is a much more difficult feat than you might suppose. Many security systems have been broken because the PRNG was imperfect.

In V5R1, OS/400 implemented a cryptographically strong PRNG. Many system components use the system PRNG. In addition, two APIs are available for your use — Generate Pseudorandom Numbers and Add Seed for Pseudorandom Number Generator. (For more information about the iSeries pseudorandom number generator, refer to the iSeries Information Center documentation listed in Find Out More.)

Cryptographic Services has three APIs for generating key values: Generate Key Record, Generate Symmetric Key, and Generate PKA Key Pair. All three APIs use the system PRNG to generate cryptographically strong pseudorandom key values.

Backing Up Keys

Keeping a current backup of all your keys is essential. In V5R4, you must back up your master keys by saving their passphrases. Master key passphrases should not be stored on the system in plaintext. Also, do not encrypt them under any of the system's master keys or any key encrypted under a master key. If the master keys are lost (e.g., when the LIC is installed) or damaged, you cannot recover the passphrases, and therefore you cannot recover the master keys. Store the passphrases securely outside the system, such as in a safe. Additional help for saving and restoring master keys is planned for a future release.

Any time a new key is added to a key store file, you should make a backup of the file. In addition, any time the key store file is translated, you need to make a new backup of the file.

Do not forget about keys stored outside of the key store. These should be backed up as well. Generally, these should not be encrypted under a master key. If you store a key outside of the key store, it is best to encrypt it under a KEK. If you encrypt it under a master key and that master key is changed, you must remember to translate the key as I described previously.

Key Formats

V5R4 Cryptographic Services supports the specification of several new key formats. New structures for these formats have been defined for the Key Description parameter of the Encrypt Data, Decrypt Data, Calculate MAC, Calculate HMAC, Calculate Signature, and Verify Signature APIs.

Key store label. You can specify the file name, library, and label for a key in a Cryptographic Services key store file on any of these APIs.

PKCS #5. RSA Security's Public Key Cryptography Standard #5 derives a symmetric key from a password, a salt, and an iteration count. The password must be kept secret. The salt value, which need not be secret, is used to produce a large set of key possibilities for each password. Therefore, the salt should be a good random value. The iteration count is used to increase the length of computation. Using a large iteration value makes an exhaustive search for the key prohibitive. You can specify PKCS #5 format on the Encrypt Data, Decrypt Data, Calculate MAC, and Calculate HMAC APIs. (For more information about PKCS #5, refer to the standard listed in Find Out More.)

PEM formatted certificate. PEM is a standard for secure electronic mail over the Internet. A PEM formatted certificate is a public-key certificate that is base64 encoded and has the text "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" appended to the beginning and the end. (A public-key certificate is basically a digital ID that can be verified. It contains a serial number, the owner's name, the issuer's name, validity dates, the public key component of the owner's RSA key pair, and a digital signature that the issuer creates. Base64 is an encoding scheme in which any arbitrary sequence of bytes is converted into printable ASCII characters.) You can specify a PEM formatted certificate on the Encrypt Data, Decrypt Data, and Verify Signature APIs. (For more information about PEM formatted certificates, refer to RFC 2127, listed in Find Out More.)

Certificate label. A label identifies a public key in a public-key certificate located in i5/OS Certificate Store. You can specify a certificate label on the Encrypt Data, Decrypt Data, and Verify Signature APIs.

Distinguished name. A distinguished name (the certificate owner) identifies a public key in a public-key certificate located in i5/OS Certificate Store. You can specify a distinguished name on the Encrypt Data, Decrypt Data, and Verify Signature APIs.

Application identifier. An application identifier identifies the private key associated with a public-key certificate in i5/OS Certificate Store. You must use Digital Certificate Manager (DCM) to create an application definition and assign a certificate to it before performing an operation with a private key. You can specify an application identifier on the Encrypt Data, Decrypt Data, and Calculate Signature APIs. For more information about DCM and i5/OS Certificate Store, refer to the iSeries Information Center article listed in Find Out More.

Key Distribution

You can use the Cryptographic Services APIs to implement a key negotiation protocol. However, key negotiation protocols are complex and beyond the scope of this article. For practical and detailed information about setting up key negotiation, refer to the resources listed in Find Out More.

Key Protection Is Key to Protecting Your Data

Assuming that you are using appropriate algorithms and key sizes (see "Cryptographic Services Tips and Techniques," below), an attack by breaking an algorithm or performing an exhaustive key search is unlikely. More likely, an attacker will look for an improperly protected key. V5R4 i5/OS Cryptographic Services helps you secure your keys. A hierarchical key store provides a means for securely storing keys, and new key formats provide greater flexibility in specifying a key. Even so, you must consider carefully the authorities that you place on stored keys and APIs, use great care to protect keys sent or moved outside of the key store, and diligently back up all keys.*

Beth Hagemeister is an IBM iSeries systems software engineer with 20 years of experience developing cryptographic software for IBM S/38, AS/400, and iSeries systems. You can e-mail her at hag@us.ibm.com.