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.
† 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.
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.
| 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
HMACwithSHA1algorithm 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.
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:
This is true regardless of how many different SecureRandom objects are being seeded by the application.com.ibm.pkcs11.PKCS11Exception: Vendor defined error (0x80000075) - This device throws a
ShortBufferExceptionfor 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:
| 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
Note: 
Luna 7 users should be aware that Thales no longer ships a 32-bit version
of the cryptoki native shared library with their Luna client side software.
Luna 7 users should be aware that Thales no longer ships a 32-bit version
of the cryptoki native shared library with their Luna client side software.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.
| 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 |