Programming Using the CCA API
The API we’re going to use is the Common Cryptographic Architecture (CCA). There are more than 80 function calls, but we’ll examine only a few of them that let you do authentication and encryption. You’ll want to get a copy of the Cryptographic Services ICSF Application Programmer’s manual for future reference.
On each function call, the first four parameters are always the same. These are variables for the return code, reason code, exit data length, and exit data. The first three are full-word binary values (S9(8) in COBOL). Normally, you won’t have exit data, so code the exit data length with a value of zero, and provide a character exit data variable of 4 bytes of nulls. The return code and reason code variables will be filled in on return from the function call. Normally, you can ignore the reason code if the return code is zero. However, there are times when you can receive a non-zero reason code with a zero return code. The reason code can be important. For example, a reason code of 10000 means that your key has been re-encrypted using a new master key. Depending on how you’ve written your application, this may mean that you need to save the new encrypted key value for future use.
The first thing you may want to do in any application you write is to determine whether the ICSF hardware is present and working. ICSF doesn’t support a status call. One method to accomplish this task is to call CSNBRNG. This function will generate a random bit string, but the real value here is that the function doesn’t require any keys or difficult setup to use and will tell you if the hardware is functioning. If you receive a return code greater than zero, for example 16, you can be sure that either the hardware isn’t present, the master keys are not established, or the CSF system proc isn’t executing. In this case, there’s no point in continuing. The CSNBRNG function requires only two additional parameters: the key form and the returned random bit string. The 8-byte key form parameter can be either “RANDOM” or “ODD.”
Many of the functions require a key value parameter. This is always provided as a 64-byte area and can consist of either a key label or key token. A key label is the name of a key you’ve defined and stored in the key data set using a TKE terminal or through API function calls. The key label must be blank padded to the full 64 bytes. A key token is also 64 bytes, but is formatted by the CCA API interface and can contain a working key encrypted by the master key, or an exported key encrypted by a key encrypting key. Key encrypting keys are special keys in the hardware used to import and export key values into and out of the hardware. For example, an exported key can be used to transfer a key value from one ICSF hardware to another where each have different master keys. Key encrypting keys are also called importer and exporter keys.
The key can be a key label that’s already defined or a working token value. In either case, the key must have been defined for authentication use and not for encryption. Strictly speaking, a key is a key, but ICSF enforces the use of a key for a specific purpose. For example, when defining a key for single DES authentication, use the MAC type. For Triple-DES authentication, use the DATAM type. For encryption, use the DATA type for all key lengths.
To create a MAC for some data, you can call the CSNBMGN function. If you just need to create a MAC for data in memory, then you can do this with one call to the routine. Two of the parameters are the data and length of the data. The rule count should be three. The rule array depends on the algorithm you choose and the form of the returned MAC you desire. Each entry in the rule array consists of 8 bytes. To select DES, use “X9.9- 1”; for Triple-DES, use “X9.19OPT.” Often, the form of the code is 9 bytes of hex characters with a blank in the middle. For this option, use “HEX-9.”
For example, to calculate a MAC for a string of data using Triple-DES, you might code something like the COBOL example in Figure 4. You can use other languages, such as Assembler, PL/1, or C.
WS-RULE2, ONLY, indicates you’re calling the function only once with all the data. The WS-CHAINING variable is used and maintained internally. You use this variable when you must call the CSNBMGN function multiple times to calculate only one MAC. The variable provides continuity for CSNBMGN to keep track of intermediate results and thus cannot be modified between calls. On the first call, you always start with the variable containing all NULL values.
The resulting MAC is returned in the WS-MAC variable, provided you receive a zero return code.