AIX > Administrator > Security

Tokenized Encryption: Cryptographic Documentation Is Necessary

Cryptographic Documentation

This is part one of a multi-part article.

Documentation in IT—and, probably, most disciplines—is an unpopular task. It's often ignored in the interest of a shortened project timeline, and it’s generally despised by many programmers, managers and other employees whose job responsibilities include the need to record and communicate information.

Personally, I don’t get it—and not just because I love writing. As a consultant, performing projects is central to my job. Invariably, when the organization I'm working with has decent documentation, the job gets done much more quickly and effectively. Maybe it’s because many IT people lack writing skills or find the process tedious and easy to put off, but documentation is a seriously ignored and undervalued asset. Documentation is an incredibly and indisputably vital component in IT. It's like an owner's manual for the department. Partly because it’s reviewed during the mandatory annual Payment Card Industry (PCI) compliance audit, and partly because it’s the glue that keeps PCI compliance infrastructure and function operational, supporting documentation should be extensive and detailed.

Documentation takes many forms: procedures, manuals, checklists, books, guides, audio and video. This includes how-to information, specifications, Q&As, guidance, historical/archival data, step-by-step instructions and a plethora of other information formats. Regardless of its form, documentation provides useful data that would otherwise have to be garnered through time-consuming investigation, testing, interviews, debugging and/or diagnostic information, and numerous other ways.

When I built a cryptographic interface for a client during its PCI compliance implementation, a variety of documentation was needed. This included procedural, operational and usage information that addressed functions like coding to the programming interface, testing and debugging, generating encryption keys, manipulating encryption facilities, generating security definitions and executing emergency procedures. Documentation also included end-user guidelines, project plans, cutover procedures, backup and recovery guidelines and numerous other aspects of a sensitive data protection and restoration methodology.

This article examines a mainframe-based cryptographic interface oriented to CICS Transaction Server and MVS, but the principles and concepts apply to all IT systems. Function and implementation may vary. Except for specific programming languages and software, this information applies to all platforms.

The CPCICI User’s Guide

The centerpiece of cryptographic interface documentation was the Cryptographic and PCI Compliance Interface (CPCICI) User’s Guide, comprised primarily of an in-depth dissertation of the programming interface and followed by a compendium of all relevant documentation. A key objective was to integrate all CPCICI information in one document, some of it separate but accessible via links to a common server. The CPCICI User’s Guide contained more than 50 pages of information and links.


The CPCICI User’s Guide was made up of several sections:

  • CPCICI Overview
  • CPCICI Functions
  • CPCICI Subroutines
  • CPCICI Error Handling
  • CPCICI Storage Layouts
  • CPCICI Related Documentation


Programmers needed to understand the purpose and function of the interface before delineating the details of how it was done. The user’s guide starts by enlightening the reader to the programming methodology and techniques built into the interface and detailing the premise and objectives on which it was built. It also covered, how the interface enabled interaction with cryptographic software and hardware to protect sensitive data. The opening section laid a foundation for understanding the cryptographic interface by describing how it evolved and how it could be used, and introduced programming techniques and examples:

  • The first topic discussed was PCI compliance. Why it had been established? What does it consist of? What is it designed to accomplish? Then came an elaboration on how it would impact enterprise online and batch computer systems and other functions such as physical access, security, and record-keeping. A brief implementation plan overview was provided. This covered how systems would be modified, how this would be supported and finally, how functions were being extended to other business data like checking account data (CAD) and Social Security Numbers (SSN).
  • The cryptographic interface was covered with a review of functionality, how calls were coded, how data was passed, how errors should be handled and how sensitive data should be treated.
  • Batch processes were explained: When they could be used? What are the recovery/restart and data-sharing considerations? What are the security guidelines and requirements?
  • The overview concluded by identifying the necessary modifications to existing sensitive-data programs, explaining code changes, data substitutions, error detection and handling, standardization of coding changes and utilization of pre-built copy books to streamline the conversion process.

Jim Schesvold is a technical editor for IBM Systems Magazine. Jim can be reached at

Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.

comments powered by Disqus



2018 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

A Bankable Solution

AIX Cryptographic Services improves security while simplifying administration

AIX Security Tools You Can Use

A look at new AIX security capabilities.

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters