External programming interfaces

Applications can directly access the cryptographic device driver through an API.

Programmers: This information is intended for those who want to program against the cryptographic device driver or against the available cryptographic libraries.

If you want to circumvent libica and directly access the cryptographic device driver, see the cryptographic device driver header file in the Linux source tree:
/usr/include/asm-s390/zcrypt.h

For information about the library APIs, see the following files in the Linux source tree:
  • The libica library /usr/include/ica_api.h
  • The openCryptoki library /usr/include/opencryptoki/pkcs11.h
  • The CCA library /opt/IBM/<prod>/include/csulincl.h, where <prod> is specific to the particular hardware product.
  • The EP11 library /usr/include/ep11-host-devel/ep11.h and ep11adm.h.

ep11.h, ica_api.h, and pkcs11.h require the devel packages to be installed. csulincl.h is present after the CCA library is installed.

Clear key cryptographic functions

The libica library provides a C API to clear-key cryptographic functions that are supported by Z hardware. You can configure both openCryptoki (using the icatoken) and openssl (using the ibmca engine) to use clear-key cryptographic hardware support through libica. See libica Programmer's Reference, SC34-2602 for details about the libica functions.

If you must circumvent libica and access the cryptographic device driver directly, your user space program must open the z90crypt device node and submit the cryptographic request using an IOCTL. The IOCTL subfunction ICARSAMODEXPO performs RSA modular exponent encryption and decryption. The IOCTL ICARSACRT performs RSA CRT decryption. See the cryptographic device driver header file in the Linux source tree:
/usr/include/asm-s390/zcrypt.h

Secure key cryptographic functions

To use secure key cryptographic functions in your user space program, see Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide, SC33-8294. You can obtain this publication at www.ibm.com/support/knowledgecenter/linuxonibm/liaaf/lnz_r_cca.html .

To use secure key cryptographic functions in your user space program by accessing an EP11 coprocessor adapter, see Exploiting Enterprise PKCS #11 using openCryptoki, SC34-2713. You can obtain it at www.ibm.com/support/knowledgecenter/linuxonibm/liaaf/sec_hw_supp.html

Reading true random numbers

To read true random numbers, a user space program must open the hwrng device and read as many bytes as needed from the device.
Tip: Using the output of the hwrng device to periodically reseed a pseudo-random number generator might be an efficient use of the random numbers.