Next, you must configure the JCA IBMPKCS11Impl provider to use openCryptoki. You need to create an IBMPKCS11Impl configuration file to tell IBMPKCS11Impl where to find the PKCS#11 implementation and what slot to use. Figure 4 shows the format of this file, which may be saved under an arbitrary path name (e.g., to /root/zpkcs.cfg).
Configure JCA to use specific providers. Locate the java.security file:
# find / -name java.security
There may be more than one, so choosing the java.security file of the Java installation being used is critical. To keep the example as simple as possible, JCA was configured to work with only two providers, the IBMPKCS11Impl provider as the primary provider and the IBMJCE provider as the fallback for all cryptographic functions not supported by IBMPKCS11Impl and openCryptoki with the icatoken. The icatoken itself provides all the cryptographic functions called in the sample program. However, when opening crypto libraries such as IBMPKCS11Impl, Java by itself requires some cryptographic functions not explicitly called in the sample program. For that reason, some mechanisms such as CKM_SHA1 are excluded from use with the IBMPKCS11Impl provider. For more complex applications, you may need to exclude additional mechanisms.
You must edit the java.security file so it only supports the IBMPKCS11Impl and IBMJCE providers. You can do this by deleting all the security provider definitions and adding the two lines with provider information shown in Figure 5.
You may need to replace the file name, /root/zpkcs.cfg, with the name chosen for IBMPKCS11Impl configuration file on the target system. Each security provider definition must be on its own line. Java isn’t forgiving when unexpected line breaks appear or line breaks are missing.
Programs that use openCryptoki should be a member of the UNIX group pkcs11. A user must be a member of this group to run the sample program. The program should now use the CPACF functions for AES encryption and decryption, via openCryptoki, with the icatoken and libica.
You can use the icastats command to verify that the hardware was accessed. When using icastats, note that libica writes usage counters for its cryptographic functions into a shared memory segment. This shared memory segment only exists as long as one or more processes are using libica. A trick to prevent the shared memory segment from being deleted after the program ends is to start a long-running process using libica (e.g., openssl speed with the ibmca engine enabled) and suspend the process with ctrl-z.
Cryptographic Hardware for Secure Key Encryption
To use secure key cryptography, a Crypto Express coprocessor must be online in the Linux image. You must insert the device driver for crypto adapters into the kernel with the modprobe z90crypt command. You can use the lszcrypt tool to check whether a coprocessor is available. The CCA library must then be installed. It isn’t part of any distribution, but you can download for free the RPM Package Manager (RPM) containing the library, along with some tools at www-03.ibm.com/security/cryptocards/. Once you’ve installed the CCA RPM, set the master key on the coprocessor. You can do this either with the Trusted Key Entry (TKE) console or the panel.exe tool included in the RPM. (For information on how to install CCA and set the master key on a crypto adapter with the panel.exe tool, refer to “Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide,” online at www-03.ibm.com/security/cryptocards/pciecc/pdf/SC33-8294-03.pdf.)