Coding a simple mainframe cryptography program

How do you code a System z cryptography program? Mainframe expert Robert Crawford takes you through the process of using the Integrated Cryptographic Service Facility.

I've learned a little more about mainframe cryptography since last month's overview. This month I'll go over a few details needed to code a simple cryptography program. For simplicity's sake, I used the lowest common denominator encryption algorithm with the fewest options. Cryptography quickly become a lot more complicated depending on operational requirements and the complexity of relationships between the entities exchanging encrypted data.

Integrated Cryptographic Service Facility
The Integrated Cryptographic Service Facility (ICSF) provides the application programming interfaces (APIs) to System z cryptographic facilities. A quick glance at the Application Programmer's Guide (APG) table of contents reveals calls that can do everything from creating an export key to generating random numbers. Resource Access Control Facility (RACF) globally controls access to ICSF APIs through the CSFSERV resource class. Likewise, each call has its own profile within that class.

Diving deeper into the APG, you will find encryption/decryption services named encipher/decipher, which are called via the CSNBENC and CSNBDEC functions. Both routines can be called from Assembler as well as high-level languages. RACF protects these APIs with profiles CSFENC and CSFDEC, respectively.

Choosing an algorithm
Many of the following steps depend on the chosen cryptography algorithm. Selecting a technique depends on security requirements as well as available hardware. Speed and performance may also come into consideration for online or mission-critical applications.

The ICSF software supports a number of encryption schemes and algorithms. In the simple case of encrypting an "at-rest" dataset to be decrypted for later use, we must use a symmetric algorithm that allows us to encrypt and decrypt the file with just one key. For this type of processing, the two leading candidates are different flavors of the Data Encryption Standard (DES). The strongest candidate is Triple DES (TDES), with a 168 bit key, and an alternative is the Advanced Encryption Standard (AES), supporting 128 bit keys.

AES is newer and considered the stronger of the two algorithms. However, there are some hardware dependencies as well as implications if the data is to be exchanged with other agencies. In this instance we can settle on TDES as the lowest common denominator.

After choosing the algorithm, the brave programmer must contact the security department to generate the key. Once security has the key, it does not send the key back to the programmer. Instead, the key is stored in ICSF with an appropriate label, which is passed back to the programmer. The programmer, of course, uses the label to reference the key during any encryption or decryption calls.

As you've probably guessed, protecting the key is paramount in symmetric cryptography, which is why ICSF keeps an encrypted copy in a VSAM data set with carefully controlled access. In addition, RACF controls access to the key based on the key label in resource class CSFKEYS. Administering this rule may get interesting if, for instance, an enterprise uses cryptography in an online application where all the users, including Web clients, need access to the key.

Encipher and decipher
The encryption/decryption routines both have long, complicated parameter lists that the APG describes with daunting cryptographic jargon. However, after some careful reading and crossed fingers, you can code acceptable encryption and decryption routines without making anything too complicated.

The high points of the parameter lists include the following:

  • ICSF return code
  • ICSF reason code. You will need both the return and reason codes to understand why something went wrong.
  • Key label, which can be up 64 bytes
  • Cipher text and length
  • Clear text and length
  • An 18-byte ICSF work area described as a chaining vector. According to the documentation, the calling program must not change this area between ICSF calls, as the work area comes into play depending on the information in the rule array (as explained below).
  • A rule array consisting of 8-byte control words specifying processing control information. The control word, representing the processing rule, is mandatory, while the subsequent ones are optional. The programming guide dedicates a lot of verbiage to describing the processing rules, as well as how they operate and affect the cipher text length. For this example I choose a processing rule of CUSP, ensuring the cipher text will be the same length as the plain text. CSUP also avoids specifying additional rules.
  • Number of rules in the above array.

In addition to the other parameters there are some others that aren't necessary for simple cryptography. These include exit data, exit data length, pad character and initialization vector.

Once the cryptographic calls work it becomes a simple matter of wrapping it with code for reading clear text records and writing encrypted data. The CUSP option ensures the cipher text will have the same length as the input records so the program won't have to worry about changing logical record lengths or block sizes.

Decrypting the cipher text becomes the reverse of the above in calling CSNBDEC with a very similar parameter list. A relatively simple encryption/decryption program can also easily expand into some sort of utility by including the flexibility to use different key labels.

As long as the requirements stay the same, this technique can be used in online applications as well. However, as mentioned before, the basic technique may need modification for performance and operational concerns. In addition, cryptography of operational data opens a huge can of worms for disaster recovery.

ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.

What did you think of this feature? Write to SearchDataCenter.com's Matt Stansberry about your data center concerns at [email protected].

Dig Deeper on IBM system z and mainframe systems