IBM PKCS11 Cryptographic Provider

The IBMPKCS11Impl provider uses the Java™ Cryptography Extension (JCE) and Java Cryptography Architecture (JCA) frameworks to seamlessly add the capability to use hardware cryptography using the PKCS#11 Cryptographic Token Interface standard.

This provider takes advantage of hardware cryptography within the existing JCE architecture and gives Java programmers significant security and performance advantages of hardware cryptography with minimal changes to existing Java applications. Because the complexities of hardware cryptography are taken care of within the normal JCE, advanced security and performance using hardware cryptographic devices is made easily available.

PKCS#11 is a standard that provides a common application interface to cryptographic services on various platforms using various hardware cryptographic devices.

Hardware Cryptographic Cards supported by the IBMPKCS11Impl crypto provider

The following table shows when support for a card was introduced in the SDK. An SR or SR FP number means that support for the card was introduced in the specified service refresh, or service refresh fix pack, of that release of the SDK. Click the name of a card to see more information about that card, such as observations of function or tested levels, later in the topic.

Important: Support for the use of these cards through the IBMPKCS11Impl provider begins after the card, the card driver, and any associated support software are installed and functioning properly. Questions or issues regarding the installation or configuration of these cards, or the accompanying software, should be directed to the manufacturer.

Table 1. The cryptographic cards that are supported on various levels of IBM SDK, Java Technology Edition
Supported cryptographic cards	Operating system	SDK Version 8 support
IBM® Crypto Express® 4, 5, 6, 7, and 8	SUSE Linux® Enterprise Server on 64-bit IBM Z® Red Hat Enterprise Linux on 64-bit IBM Z Ubuntu on 64-bit IBM Z z/OS® (31-bit and 64-bit)^†	yes (IBM Crypto Express 6 and 7 from SR5 FP25 , IBM Crypto Express 8 from SR8 FP15)
Thales Luna 7 (SDK Version 8 only)^‡	AIX® Linux Solaris Windows	SR5 FP35
Entrust nShield Connect XC High, XC Mid, XC Base^‡	AIX Linux Windows	SR5 FP20
Entrust Solo XC High, XC Mid, XC Base^‡	AIX Linux Windows	SR5 FP20
Entrust nShield Edge	Windows	yes

† To use the IBMPKCS11Impl provider on z/OS, you must have ICSF running on a system with a supported cryptographic hardware configuration as described in Cryptographic Services Integrated Cryptographic Service Facility Overview, Appendix B, Summary of callable service support by hardware configuration.
‡ The manufacturer-supplied software that accompanies the card determines the operating systems on which you can use the card. Questions or issues regarding the supported operating systems for a card should be directed to the manufacturer.

The following cards are no longer supported by the manufacturer and so are no longer supported in the SDK:

IBM 4764 Cryptographic Coprocessor
IBM 4765 Cryptographic Coprocessor
IBM Crypto Express 2
IBM Crypto Express 3
Entrust nShield Connect 500
Entrust nShield Connect 1500
Entrust nShield Connect 6000
IBM e-business Cryptographic Accelerator (4960, PCICA)
Thales Luna SA 4.0, 4.5, 5.0, and 6.0
Entrust nShield Connect 500+, 1500+, 6000+
Entrust Solo 500+, 6000+

IBM Crypto Express 4, 5, 6, 7, and 8

Note: An IBM Crypto Express adapter that is configured as a CCA token cannot be used by SSL or TLS to access keys or certificates. If you are using an IBM Crypto Express adapter and SSL or TLS, configure the adapter as a ICA token.

Card observations include:

Elliptic Curve Cryptography algorithms are not supported.
The Blowfish algorithm is not supported.
The HMACwithSHA1 algorithm is not supported.
For the RSAPSS signature algorithm, if RSAPSS parameters are provided, the salt length value specified must either be equal to zero, or equal to the output length of the hash algorithm specified.

You can use the pkcsconf -m command to display the supported mechanisms for each slot on a Linux on IBM Z system.

IBM Crypto Express cards on Linux on IBM Z require openCryptoki 3.9 or above to operate.

Start of changes for service refresh 5 fix pack 35

Thales Luna 7 (SDK Version 8 only)

Card observations include:

Private software keys cannot be translated using this card. Set publickeyimportonly = true in the PKCS#11 configuration file to ensure that the provider will not attempt to translate private software keys.
Key wrapping does not work with the default configuration of the device.
If the SecureRandom.setSeed() method is called more often than once every 10 seconds, the Luna 7 card throws the following exception:
```
com.ibm.pkcs11.PKCS11Exception: Vendor defined error (0x80000075)
```
This is true regardless of how many different SecureRandom objects are being seeded by the application.
This device throws a ShortBufferException for buffers that are too small.
The Blowfish and MD5 mechanisms are not supported.
The JSSE TLS 1.2 protocol cannot successfully use ECDH CipherSuites with the IBMPKCS11Impl provider and a Thales Luna HSM. This is a permanent restriction. If you want to use JSSE, use ECDHE CipherSuites instead.

The following software and firmware levels were tested:

Table 2. Software and firmware levels tested for Thales Luna 7 cards
Software or firmware	Thales Luna 7
Thales Luna Network 7 model A790 software version	7.2.0-220
Thales Luna Network 7 model A790 firmware version	7.0.3
Luna client software version	7.3

The following Thales Luna 7 models are supported:

Thales Luna Network 7 HSM (network-attached HSMs):
- A700, A750, and A790, all with password authentication
- S700, S750, and S790, all with PED authentication
Thales Luna PCIe 7 HSM (PCI-Express cards):
- A700, A750, and A790, all with password authentication
- S700, S750, and S790, all with PED authentication

These models all use the same Luna 7 firmware.

End of changes for service refresh 5 fix pack 35

Entrust nShield Connect XC, nShield Solo XC, nShield Edge

Card observations include:

RSA keys can wrap a DES or DESede key, but DES and DESede key cannot wrap an RSA key. Public keys cannot be wrapped.
Translation of plain RSA keys is not supported. RSA CRT keys can be translated.
Random number seeding is not supported. Setting a seed for the random number generator is not allowed.
Hardware private key, the DERIVE and SIGN attribute values cannot be configured to true at the same time. Therefore, one private key cannot be used for both signing and key agreement.
For the RSAPSS signature algorithm, if RSAPSS parameters are provided, the salt length value specified must be equal to the output length of the hash algorithm specified.

The following software and firmware versions were tested. If you are using these cards, ensure that you use the same, or later, firmware and software versions.

Table 3. Software and firmware versions tested for Entrust cards
Software or firmware	Entrust nShield Connect XC High (SDK Version 8 only)
Entrust client system software version	12.40.2
Entrust HSM software version	12.40.0
Entrust HSM firmware version	3.3.33