As of V5R4, i5/OS now includes key stores. Technically, key stores have an object type of *FILE -- and more specifically, a physical data base file -- but data access to key stores is only possible through the Cryptographic Services APIs. Key stores offer the option of storing key encryption keys or data keys, securely encrypted under a master key. If you are unfamiliar with the concepts of master keys, key encryption keys, and data keys, please see my earlier Cryptographic Key Management articles, which cover those topics in more detail; links are provided at the end of this article.
The Cryptographic Services APIs for managing key stores provide a variety of functions, such as creating a key store, generating or writing a key store record, and deleting a key store record. Other key store APIs let you retrieve the attributes of a key store record or translate all the key store records in a key store encrypted with one master key to another. To discuss key stores in more detail and provide some key store API coding examples, today's issue of APIs by Example presents a pair of CL commands named Create Key Store (CRTKS) and Translate Key Store (TRNKS) that are based on the respective APIs.
The Cryptographic Services APIs that require a key as input to a cryptographic operation have had added a new KEYD0400 key description parameter format to enable the use of key encryption keys or data keys stored in a key store. This new format lets you specify a qualified key store name and a key label for the key parameter. The key label is the name that uniquely identifies a specific key store record within a key store; you define it when you add the key record to the key store. I discuss key store records in more detail in a moment, and an upcoming APIs by Example will look more closely at the options and methods controlling the management of key store records.
Specifying the KEYD0400 format as input to a Cryptographic Services API causes the API to retrieve the key from the key store and decrypt it with the master key associated with the key store. While in the key store, the key is encrypted and thereby securely protected by the master key. The option of specifying the key store record directly to a Cryptographic Services API lets you maintain a closed circuit for the duration of the entire encryption process performed by that API, thus avoiding the exposure of the key outside of the API domain.
However, this circumstance requires careful consideration on your part to ensure that users are given proper authorization to both the key stores and the APIs involved. Anyone obtaining this access will be able to extract the key from the key store, or use it to retrieve the data encrypted under it. Likewise, it.s very important that you include key stores in your backup schedule to enable recovery of the key encryption keys and data keys stored there. Imagine if you had a system failure, and restored your data to a new computer, only to learn that none of the encrypted data is accessible because the key stores are gone! Further backup considerations apply at the point where new key store records have been added or the key store has been translated. I explain key store translation shortly, so bear with me if this is an unfamiliar term to you.
Key stores are a great addition to the Cryptographic Services APIs and the cryptographic infrastructure included in i5/OS -- let's look at how to create them with the Create Key Store (QC3CRTKS/Qc3CreateKeyStore) API. This API can be called as a program named QC3CRTKS, or as an ILE procedure named Qc3CreateKeyStore. For ease of use and to provide an example of how to call the API, I.ve created a Create Key Store (CRTKS) CL command -. here.s what the CRTKS command prompt looks like:
Create Key Store (CRTKS)
Type choices, press Enter.
Key store . . . . . . . . . . . Name
Library . . . . . . . . . . . *CURLIB Name, *CURLIB
Master key ID . . . . . . . . . 1-8
Text 'description' . . . . . . . *BLANK
Authority . . . . . . . . . . . *EXCLUDE Name, *EXCLUDE, *LIBCRTAUT...
|
You specify a qualified key store name, the Master Key ID of the master key you want to associate with the key store, as well as an optional text description and the public authority to assign to the key store. Please note that the specified Master Key ID need not be set at the point where the key store is created, but rather when key store records are actually added.
For the reasons explained earlier, I have defaulted the public authority I have to *EXCLUDE. But remember that object authority offers no protection against user profiles that have *ALLOBJ special authority in the profile! Careful planning of your user profile and object authorization scheme is still of utmost importance to ensure a safe and secure cryptographic infrastructure.
To try out the CRTKS utility, run the following command to create a key store by the name of KEYSTORE01 in the QGPL library:
CRTKS KEYSTORE(QGPL/KEYSTORE01)
KEYID(7)
TEXT(*BLANK)
AUT(*EXCLUDE)
If the above CRTKS command completes successfully, you'll receive a completion message that verifies that the key store was created.
Message ID . . . . . . : CBX0021 Severity . . . . . . . : 00 Message type . . . . . : Completion Date sent . . . . . . : 19-01-08 Time sent . . . . . . : 11:40:40 Message . . . . : Key store KEYSTORE01 created in library QGPL. Cause . . . . . : The key store KEYSTORE01 was successfully created in library QGPL. The master key ID 7 will be used to encrypt the cryptographic keys stored in the key store. |
To verify that a key store was created as opposed to an ordinary physical file, try executing the Run Query (RUNQRY) command against it. You will receive the QRY2293 exception message: Query cannot be run. See lower level messages. Checking out the job log leads to the discovery of a CPF4234 diagnostic message preceding the QRY2293 exception message:
Message ID . . . . . . : CPF4234 Severity . . . . . . . : 50 Message type . . . . . : Diagnostic Date sent . . . . . . : 19-01-08 Time sent . . . . . . : 11:55:51 Message . . . . : Input or output operations for member KEYSTORE01 not allowed. Cause . . . . . : Member KEYSTORE01 file KEYSTORE01 in library QGPL could not be opened because it does not allow any input or output operations. The input and output operations allowed for member KEYSTORE01 are contained in the attributes specified for file KEYSTORE01 in library QGPL. The attributes of the file can be displayed by using the DSPFD command. |
The Display File Description (DSPFD) explains the cause of the above CPF4234 diagnostic message. Note the bolded part of this excerpt of the DSPFD command output:
19-01-08 Display File Description
DSPFD Command Input
File . . . . . . . . . . . . . . . . . . . : FILE KEYSTORE01
Library . . . . . . . . . . . . . . . . . : QGPL
Type of information . . . . . . . . . . . . : TYPE *ALL
File attributes . . . . . . . . . . . . . . : FILEATR *ALL
System . . . . . . . . . . . . . . . . . . : SYSTEM *LCL
File Description Header
File . . . . . . . . . . . . . . . . . . . : FILE KEYSTORE01
Library . . . . . . . . . . . . . . . . . . : QGPL
Type of file . . . . . . . . . . . . . . . : Physical
File type . . . . . . . . . . . . . . . . . : FILETYPE *DATA
Auxiliary storage pool ID . . . . . . . . . : 00001
Data Base File Attributes
Externally described file . . . . . . . . . : Yes
SQL file type . . . . . . . . . . . . . . . : TABLE
File level identifier . . . . . . . . . . . : 1080119114039
Creation date . . . . . . . . . . . . . . . : 19-01-08
Text 'description' . . . . . . . . . . . . : TEXT
Distributed file . . . . . . . . . . . . . : No
Partitioned SQL Table . . . . . . . . . . . : No
DBCS capable . . . . . . . . . . . . . . . : No
Maximum members . . . . . . . . . . . . . . : MAXMBRS 1
Number of constraints . . . . . . . . . . . : 1
Number of triggers . . . . . . . . . . . . : 0
Number of members . . . . . . . . . . . . . : 1
...
Reuse deleted records . . . . . . . . . . . : REUSEDLT *YES
Coded character set identifier . . . . . . : CCSID 65535
Allow read operation . . . . . . . . . . . : No
Allow write operation . . . . . . . . . . . : No
Allow update operation . . . . . . . . . . : ALWUPD *NO
Allow delete operation . . . . . . . . . . : ALWDLT *NO
Record format level check . . . . . . . . . : LVLCHK *YES
Access path . . . . . . . . . . . . . . . . : Keyed
Access path size . . . . . . . . . . . . . : ACCPTHSIZ *MAX1TB
Access path logical page size . . . . . . . : PAGESIZE *KEYLEN
Maximum key length . . . . . . . . . . . . : 97
Maximum record length . . . . . . . . . . . : 2556
...
|
As you can see, none of the data access operations are allowed for key store files: Read, write, update and delete operations are all prohibited. None of these attributes, however, prevent you from displaying the key store record format. Using the Display File Fields (DSPFFD2) command (presented in an earlier APIs by Example article) reveals the following database record format layout:
File . . . . . . : KEYSTORE01 Record length . : 2556 Library . . . : QGPL Field count . . : 10 Record format . : KEYSTORE01 File type . . . : PF Include field . . Access path . . : *KEYED UNIQUE Include text . . . Field Data type Buffer Length Dig Dec Key Text KYLABEL Char 1 97 1 A RESRV1 Char 98 3 KEYTYPE Binary 101 4 9 0 KEYSIZE Binary 105 4 9 0 TIMEDATE Char 109 4 KVV Char 113 20 KYVARIANT Binary 133 4 9 0 CHECKSUM Binary 137 4 9 0 RESRV2 Char 141 2 TOKEN Var Char 143 2414 |
The above record format applies to all i5/OS key store files and the attributes together define the information stored in a key store record. But more about key store records next time. If you want to delete the key store created earlier, you can do so using the Delete File (DLTF) command:
DLTF FILE(QGPL/KEYSTORE01)
The second command I present today, Translate Key Store (TRNKS), is also based on a corresponding API -- the Translate Key Store API is named QC3TRNKS and Qc3TranslateKeyStore for the OPM and ILE versions, respectively.
Translation in this context reflects the event that the keys in the key store are first decrypted using the master key that originally encrypted the keys and, in the same process, immediately following decryption the keys are again encrypted using another master key. The need to perform this re-encryption process could be prompted by one of two circumstances:
The same master key ID has changed version since the original encryption of the key store records. This occurs if, using the Set Master Key command or API, a new master key version has been promoted to the current version, and the original version has been saved to the old version. To avoid the possible loss of the old master key version, should someone repeat the aforementioned process, I recommend that you translate all keys still encrypted under the old version of the master key to the current version as soon as possible, after you set the master key.
Suppose you decide to change the master key ID associated with a key store. Say a key store is currently associated with master key ID 1 and you need to change the key store master key to master key ID 2. You can use the TRNKS command or API to do this. The same precautions mentioned above apply here as well.
As you can see below, the Translate Key Store (TRNKS) command has a quite simple interface:
Translate Key Store (TRNKS)
Type choices, press Enter.
Key store . . . . . . . . . . . Name
Library . . . . . . . . . . . Name
+ for more values
Master key ID . . . . . . . . . 1-8
|
You can specify up to 32 different key stores in one execution of the TRNKS command. The TRNKS API will process each key store in turn, using the currently associated Master Key ID and the stored Key Verification Value (KVV) to locate the correct version of the master key (as explained last time) to decrypt all keys. Then, immediately following decryption, the current version of the specified master key ID is used to re-encrypt the keys. Should the translation process at some point encounter an error or exception, the process will be terminated immediately, and the job log of the executing job should be consulted to establish cause and consequences.
In addition to the security, confidentiality, and authorization aspects mentioned earlier, the following conditions and considerations apply to the utilities and APIs presented in this article: The Create Key Store API only requires the usual *EXECUTE and *ADD authority to the library in which the key store is created. I.ve decided that for my system though, to further add the requirement of *ALLOBJ and *SECADM special authority in the user profile executing the Create Key Store (CRTKS) command.
This precaution reduces the number of user profiles allowed to create key stores (using the CRTKS command) significantly on systems with an adequate security configuration, and I.d like to limit potential sources of errors and mistakes as much as possible, also in the context at hand. Since the source for the CRTKS CPP is included with this article, you.re of course free to relax this restriction should you decide to do so.
The Translate Key Store API needs *OBJOPR, *READ and *UPD authority to the key store object in order to process the key store records. I.ve replaced this requirement with function usage authorization. This implies that any user that attempts to run the Translate Key Store (TRNKS) command will need to be specifically and individually authorized to the CBX_CRYPTO_KEYSTORE_XLATE that is registered by the CBX185M CL program provided with this article to build the CRTKS and TRNKS commands. The user running the CBX185M CL program will be authorized to the TRNKS command.
Use the following command to locate and change the function usage registrations applying to the key management utilities delivered with the Cryptographic Key Management articles in previous APIs by Example articles:
WRKFCNUSG FCNID(CBX_CRYPTO_*)
Given that you.ve loaded and installed the commands and usage registrations provided with this and the previous APIs by Example articles, you should see a list similar to the one below:
Work with Function Usage
Type options, press Enter.
2=Change usage 5=Display usage
Opt Function ID Function Name
CBX_CRYPTO_KEYSTORE_XLATE Cryptograhic key store translation
CBX_CRYPTO_MASTERKEY_CLEAR Clear cryptograhic master key
CBX_CRYPTO_MASTERKEY_LOAD Cryptograhic master key part load
CBX_CRYPTO_MASTERKEY_SET Set cryptograhic master key
CBX_CRYPTO_MASTERKEY_TEST Cryptograhic master key test
Bottom
Parameters for option 2 or command
===>
F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel F17=Top
F18=Bottom
|
Use option 2 to add and/or remove users. function usage. You can find more information on function usage registration prerequisites and requirements in the APIs by Example article of December 13, 2007, please follow the link provided below.
I.ll be continuing the Cryptographic Key Management coverage in upcoming issues of APIs by Example. Next time I.ll show you how to generate, display, and delete key store records, so stay tuned. And in the meantime, if you.re facing the challenge of implementing cryptographic applications of your own and looking for information and inspiration, be sure to check out the links below pointing to NIST (National Institute of Standards and Technology) publications, providing a wealth of application security and cryptography related documentation and recommendations.
This APIs by Example includes the following sources:
CBX180 -- RPGLE -- Cryptographic Key Management - Services CBX180B -- SRVSRC -- Cryptographic Key Management - Binder source CBX185 -- RPGLE -- Create Key Store - CPP CBX185H -- PNLGRP -- Create Key Store - Help CBX185X -- CMD -- Create Key Store CBX186 -- RPGLE -- Translate Key Store - CPP CBX186H -- PNLGRP -- Translate Key Store - Help CBX186X -- CMD -- Translate Key Store CBX185M -- CLP -- Cryptographic Key Management III - Build commands
To create all above objects, compile and run CBX185M. You.ll find compilation instructions in the source headers as usual. Note that the two previously published commands Add Function Registration (ADDFCNREG) and Change User Function Usage (CHGUSRFCNU) are required for the Translate Key Store (TRNKS) command to run successfully -. and for the CBX185M program to compile.
The sources for the two aforementioned user function commands were included with my previous APIs by Example article of November 8. In case you missed that article, you can find it at the link below. Successfully compiling and running the CBX180M CL setup program included with that article is a prerequisite to running the CBX185M setup program included today.
Previously published related articles:
APIs by Example: Working with Database Files, Fields and More:
http://www.iseriesnetwork.com/article.cfm?id=55705 [2] (October 11, 2007)
APIs by Example: Cryptographic Key Management - Loading and Setting Master Keys:
http://www.iseriesnetwork.com/article.cfm?id=55862 [3] (November 8, 2007)
APIs by Example: Cryptographic Key Management - Testing and Clearing Master Keys:
http://www.iseriesnetwork.com/article.cfm?id=56035 [4] (December 13, 2007)
Other related documentation:
RFC 4107 Guidelines for Cryptographic Key Management:
http://tools.ietf.org/html/rfc4107 [5]
NIST (National Institute of Standards and Technology) Special Security Publications:
http://csrc.nist.gov/publications/PubsSPs.html [6]
NIST SP 800-57: Recommendation for Key Management . Part 1:
http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf [7]
NIST SP 800-57: Recommendation for Key Management . Part 2:
http://csrc.nist.gov/publications/nistpubs/800-57/SP800-57-Part2.pdf [8]
NIST (National Institute of Standards and Technology) FIPS Publications:
http://csrc.nist.gov/publications/PubsFIPS.html [9]
IBM documentation:
i5/OS: Cryptography concepts:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rzajc/rzajcconcepts.htm [10]
Cryptographic Services Master Keys:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3MasterKeys.htm [11]
Cryptographic Services Key Store:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3KeyStore.htm [12]
This article demonstrates the following Cryptographic Services API:
Create Key Store (Qc3CreateKeyStore) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3crtks.htm [13]
Translate Key Store (Qc3TranslateKeyStore) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3trnks.htm [14]
Key Management APIs:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/catcrypt6.htm [15]
Cryptographic Services APIs:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/catcrypt.htm [16]
Links:
[1] http://systeminetwork.com/author/carsten-flensburg
[2] http://www.iseriesnetwork.com/article.cfm?id=55705
[3] http://www.iseriesnetwork.com/article.cfm?id=55862
[4] http://www.iseriesnetwork.com/article.cfm?id=56035
[5] http://tools.ietf.org/html/rfc4107
[6] http://csrc.nist.gov/publications/PubsSPs.html
[7] http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf
[8] http://csrc.nist.gov/publications/nistpubs/800-57/SP800-57-Part2.pdf
[9] http://csrc.nist.gov/publications/PubsFIPS.html
[10] http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rzajc/rzajcconcepts.htm
[11] http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3MasterKeys.htm
[12] http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3KeyStore.htm
[13] http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3crtks.htm
[14] http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qc3trnks.htm
[15] http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/catcrypt6.htm
[16] http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/catcrypt.htm
[17] http://www.pentontech.com/IBMContent/Documents/article/56187_461_CrtKsTrnKs.zip