Sample Code

CCA Sample Programs

IBM provides a Common Cryptographic Architecture (CCA) for its hardware security modules (HSMs) that includes an application programming interface (API) which is intended for systems analysts, applications analysts, and application programmers to evaluate or create programs that employ the CCA API. Users of the CCA API should refer to the manuals that are available on the IBM CCA download site. Additional information about each IBM cryptographic adapter is available on each adapter's product pages. See the Products drop-down menu on the navigation menu above the page heading.

Note: Linux® on IBM Z® users should refer to the Secure Key Solution with the Common Cryptographic Architecture: Application Programmer's Guide, which is available on the IBM Docs site.

IBM provides the following sample programs as examples of how to use and code a subset of the CCA API for the IBM HSMs. Samples that target the IBM 4769 are available on the IBM CCA download site.

Note: To access this site, you must obtain and log in with an IBMid. This process is quick and easy. Instructions are on the download site.

EP11 Sample Program

IBM's Enterprise PKCS#11 (EP11) is a mode for the CryptoExpress hardware security modules (HSMs) as well as libraries installable on zLinux that offer an application programming interface with the HSMs. On top of this API, PKCS#11 compliant libraries can be built (e.g., OpenCryptoki). Furthermore, the EP11 host library can be used directly to interact functionally and administratively with IBM's HSMs in EP11 mode when a PKCS#11 API is not needed. In the latter case, key storage and session management have to be implemented on top of the available functionality. Additional information about the EP11 Support Program is available on the Linux on Z software download page.

An EP11 example that introduces initial setup and running basic functions on an HSM is available on the IBM EP11 download site.

4769/4767 CCA Sample Programs

Access Control System Initialize one or more roles; query and list defined roles.	AES Encipher/Decipher Generate a random AES key and use the key to encipher and decipher some data.	DES Encipher/Decipher Generate a random DES key and use the key to encipher and decipher some data.	Calculate/verify MAC Generate a random HMAC key, then calculate and verify a MAC on a predetermined string of data.
Generate/Verify Digital Signature Generate a random RSA public/private key pair, then use that key pair to sign and verify some sample data.	Set Up a CCA Node Set up a CCA node for use as a development and test platform using various CCA API calls.	TR-31 Export/Import Export a DES key that is in a CCA key-token into a TR-31 key-token and import that DES key from the TR-31 key-token back into a CCA key-token.	Pin Operations Generate a random HMAC key, then calculate and verify a MAC on a predetermined string of data.
Performance Test performance of various CCA verbs.	Set Adapter Clock Get and set the adapter clock to sync it with the server clock.
TR-34 Bind 4769 only: Demonstrates the binding process of TR-34 between the Key Distribution Host and Key Receiving Host, using OpenSSL for the certificate authority.	TR-34 Export 4769 only: Demonstrates the TR-34 key export process (2-Pass or 1-Pass) between Key Device Host and Key Receiving Host, using OpenSSL for the certificate authority.	RSA x509 Sign/verify 4769 only: Uses a self-signed X.509 certificate (accepted natively by the CCA API), using OpenSSL to generate the initial keypair, signature, and certificate.	RSA x509 Symkey Export/Import 4769 only: Exports an AES symmetric key using X.509 certificate and imports and AES symmetric key using a private key, using OpenSSL to generate the X.509 certificate used for export.