| Sun Crypto Accelerator 6000 Board User’s Guide for Version 1.1 |    
|
| Sun Crypto Accelerator 6000 Board User’s Guide for Version 1.1 |
|
| C H A P T E R 6 |
Developing PKCS#11 Applications for Use With the Sun Crypto Accelerator 6000 Board |
This chapter describes the board’s implementation of the PKCS#11 interface and describes how to build customized PKCS#11 applications to be used with the board. Additional instructions for Linux platforms are included in the last section. This chapter includes the following sections:
For Oracle Solaris OS on x64 platforms, the default location for this library is /usr/lib/64/:
| Note - The 64 directory is a softlink that resolves to sparcv9 or amd64 depending on your architecture. |
The Sun Crypto Accelerator 6000 Board is registered in the Oracle Solaris Cryptographic Framework as a hardware provider. Thus, the board can be administered using the system commands. Refer to the Oracle Solaris 10 System Administration Guide: Security Services document.
The Oracle Solaris Cryptographic Framework provides a PKCS#11 library through which the Sun Crypto Accelerator 6000 Board is accessed. For Oracle Solaris SPARC platforms, the default location for this library is /usr/lib/ for 32-bit mode and /usr/lib/sparcv9/ for 64-bit mode.
PKCS#11 has a limited administrative facility with just two functions: C_InitToken, which initializes the token, and C_InitPin, which sets user PINs. The board does not use this facility, and instead uses the scamgr utility. See Chapter 3.
When a keystore is first initialized, scamgr prompts you to set up a keystore security officer (KSO) account. This keystore security officer is not related to the PKCS#11 security officer, and cannot authenticate to a board through the PKCS#11 interface.
Also during keystore initialization, scamgr prompts for the keystore name. The keystore name is used as the slot description and the token label for the Keystore slot. See Keystore Slot.
After the keystore is initialized, the security officer can create one or more users using the scamgr utility. Users created by the security officer authenticate to a keystore through the PKCS#11 interface. Since PKCS#11 is designed for a single-user system, the C_Login entry point does not take the username as a parameter. To differentiate users, a PIN must be given as a string of the form username:password. For example, if the password of user webserv is abc123, the PIN used through the PKCS#11 C_Login entry point is webserv:abc123.
There are four kinds of slots available through the Oracle Solaris PKCS#11 library.
The Keystore slot groups together the multiple hardware providers that share a common keystore to support availability and load balancing. The Keystore slot description and the token label for the Sun Crypto Accelerator 6000 Board are made up of the keystore name padded with spaces.
The Sun Metaslot uses all of the cryptographic engines on the system, including the Sun Crypto Accelerator 6000; thus, it provides the maximum functionality. By default, Sun Metaslot uses the Oracle Solaris Softtoken keystore; however it can be configured to use the Sun Crypto Accelerator 6000 keystore. See Sun Metaslot.
The Hardware slot is bound to and dedicated to a hardware device. These slots are directly accessible when the device is uninitialized or when it is in diagnostic mode. There should be three Hardware slots per Sun Crypto Accelerator 6000 board. These slots are useful for diagnosis because they are directly associated with a board. The Hardware slot description and the token label for the board are in the following format: mca/N Crypto Accel 1.0. [CB|CA|OM]. Where N is the instance number.
The Sun Softtoken slot is a software cryptographic provider with an on-disk keystore.
The following subsections provide details on the Keystore slot, Sun Metaslot, and Hardware slot.
The Keystore slot has the advantage of hardware redundancy and load balancing when there are more than one Sun Crypto Accelerator 6000 Board on the system with the same keystore. For example, when there are two boards with the same keystore with the name of ks, a slot with the slot description and token label of ks is used as the Keystore slot.
When the Keystore slot is used, a cryptographic job may be sent to either board based on the board state. If one board is fully tasked, the job is sent to the other board. Also, if one board is not available due to a hardware failure, the job is sent to the other board.
With Keystore slot, both sensitive session keys and sensitive token keys are kept secure on the board. Thus, the secure key value is never revealed clear on the host memory. If the security of sensitive session keys are required, the Keystore slot is preferred over Sun Metaslot.
The Sun Metaslot takes advantage of the Sun Crypto Accelerator 6000 Board for cryptographic acceleration along with all other cryptographic providers available on the system. The Sun Metaslot uses the board for the mechanisms it supports, and it uses other slots, including the Oracle Solaris software implementation, for the mechanisms not supported by the board. The Sun Metaslot also supports failover. For more details, please refer to the Sun Metaslot documentation.
Through Sun Metaslot, only one keystore can be accessed. By default Sun Metaslot uses the Oracle Solaris Softtoken keystore. To access the Sun Crypto Accelerator 6000 keystore through Sun Metaslot, you must use one of the following configurations.
Enter the following command to use the Sun Crypto Accelerator 6000 keystore. For the example in this section, ks is the name of the Sun Crypto Accelerator 6000 keystore.
This command forces a global change throughout the system, which causes all applications on the system to use the Sun Crypto Accelerator 6000 keystore by default.
Sun Metaslot can be configured to use the board’s keystore on a per application basis by setting an environment variable. The variable should be set to the name of the Sun Crypto Accelerator 6000 keystore.
The environment variable overwrites the system-wide configuration.
Sun Metaslot supports fail over by automatically migrating keys from the Sun Crypto Accelerator 6000 keystore to other slots. By doing so, the keys securely stored on the board might be revealed on the host memory. To protect the secure keys, enter the following command:
The auto-key migration can also be disabled on a per application basis by setting the following environment variable.
When the auto key migration is disabled, sensitive token keys are not automatically migrated to other slots. With this configuration, if an operation with a sensitive token key fails on the Sun Crypto Accelerator 6000 Board, the request does not failover to other slots, and the operation fails.
When this variable is not set, the sensitive token key is migrated to other slots that support the operation, and the request is processed in a failover slot. If the job fails over to a software slot, such as Sun Softtoken, the key could be revealed on the host memory.
| Note - This configuration applies to the sensitive token keys only. Other keys, such as nonsensitive keys and sensitive session keys are still automatically migrated for failover. |
To verify the current system-wide configuration, enter the following command:
The following output shows that the Sun Metaslot is enabled, the automatic key migration is disabled, and the keystore slot, ks, is used for the persistent object store.
When the board has not been initialized or when the board is in the diagnostic mode, the device can be directly accessed with the hardware slots. There are three hardware slots (CB, CA, and OM) per Sun Crypto Accelerator 6000 board.
The Hardware slot is dedicated to a single board and thus does not allow hardware redundancy or load balancing. For a typical application, you might want to use either the Keystore slot or Sun Metaslot . The Hardware slot, however, is useful for diagnosis.
When put in FIPS mode by the SO (using scamgr), the Sun Crypto Accelerator 6000 Board is compliant with Federal Information Processing Standard FIPS 140-2 level 3. Detailed information on FIPS 140-2 can be found at: http://www.nist.gov
Operating the board in FIPS mode causes the following changes in the board’s operation:
FIPS mode applies only to the Sun Crypto Accelerator 6000 Board itself. As stated above, when the board is put in FIPS mode, only FIPS-approved mechanisms are provided by the board. Notably, MD5, and RC2 are not FIPS-approved.
However, because the FIPS regulations apply only to the hardware, software implementation of the non-FIPS-approved mechanisms are still available through the Sun Metaslot.
The necessary header files are in /usr/include/security. Add this directory to the include path and include cryptoki.h. The lower-level include files, pkcs11.h, pkcs11f.h, and pkcs11t.h are also available in the directory. These files are identical to those available at the PKCS#11 web site: http://rsa.com/rsalabs/node.asp?id=2133/
The PKCS#11 libraries are /usr/lib/libpkcs11.so (32-bit mode) and /usr/lib/sparcv9/libpkcs11.so (64-bit mode).
The Oracle Solaris PKCS#11 library can be linked as an ordinary library, or it can be dynamically opened with dlopen (3DL).
When linking as an ordinary library, use the following command:
The PKCS#11 administrative functions C_InitToken and C_InitPin are not implemented. The C_Login function with the CKU_SO (security officer) flag is rejected.
In PKCS#11, public token objects are token objects that are visible and can be deleted without authentication. Because the users known by the Sun Crypto Accelerator 6000 software are unrelated to Oracle Solaris users, and because the software does not ascertain user identity until C_Login succeeds, these objects would need to be globally visible to all users, and therefore deletable by any user. Because this behavior is not acceptable, public token objects are not allowed. Any attempt to create a public token object will fail.
The number of session objects is limited by virtual memory only. Token objects must all fit in the RAM on the board, and the driver limits the size of the keystore to 16 Mbytes. However, the fields of the CK_TOKEN_INFO structure (returned by the C_GetTokenInfo function) that indicate maximum memory sizes are all set to CK_EFFECTIVELY_INFINITE. The C_GetObjectSize function is not implemented.
The optional dual operation functions (C_DigestEncryptUpdate, C_DecryptDigestUpdate, C_SignEncryptUpdate, and C_DecryptVerifyUpdate) are not implemented, and the CKF_DUAL_OPERATIONS_FLAG in the flags field returned by C_GetTokenInfo is false.
C_GetOperationState and its companion function C_SetOperationState are not supported.
Since the Sun Crypto Accelerator 6000 Board can only operate SHA-1 and MD5 in a single part and the PKCS#11 interface requires both single part and multipart for the hash operations, CKM_SHA_1 and CKM_MD5 are not available from the user level of the PKCS#11 application. However, those mechanisms are available for the kernel consumers, such as IPsec.
The tokens provided by the Sun Crypto Accelerator 6000 system are considered unremovable. Thus the CKF_REMOVABLE_DEVICE flag returned by CK_GetSlotInfo is false. However, the board can be dynamically reconfigured when there is no PKCS#11 application that has an active session on the board.
The C_WaitForSlotEvent function is not implemented, and the Sun Crypto Accelerator 6000 system never calls the callback function passed as the Notify parameter to C_OpenSession. The software never surrenders control back to the calling application with the pApplication parameter of C_OpenSession.
The Sun Crypto Accelerator 6000 Board contains a high-quality true random number generator. It does not need to be seeded, and in fact, C_SeedRandom will be rejected.
The Sun Crypto Accelerator 6000 software defines the default values for some attributes as listed in the following table. Some permission flags such as CKA_LOCAL and CKA_ALWAYS_SENSITIVE are not implemented or enforced as noted.
The CKA_TOKEN attribute defaults to false. The CKA_PRIVATE attribute defaults to the same value as CKA_TOKEN. An attempt to set both CKA_TOKEN and CKA_PRIVATE to false will fail since Sun Crypto Accelerator 6000 does not support public token objects.
The CKA_EXTRACTABLE attribute defaults to true. The CKA_SENSITIVE attribute defaults to the opposite of CKA_EXTRACTABLE. An attempt to set both CKA_SENSITIVE and CKA_EXTRACTABLE to false will fail with CKR_TEMPLATE_INCONSISTENT.
Inconsistent attributes are generally not detected. For example, even if CKA_VALUE_LENGTH is specified in the template when the CKK_DES key is created with C_CreteObject, Sun Crypto Accelerator 6000 software will not return an error code. The inconsistent attribute CKA_VALUE_LENGTH is simply ignored by the software.
The error codes returned by the software are not always as specific as what might be expected. In particular, CKR_MECHANISM_INVALID is returned for many errors where other values might seem more appropriate. The return code CKR_HOST_MEMORY usually means that an internal call to the malloc(3c) command failed. After this error is returned, an important state has probably not been properly saved, and attempting to continue, except by calling C_Finalize, could be ineffective.
The Mutex callback function pointers that can be passed to C_Initialize are ignored.
As required by the PKCS#11 standard, all token object handles become invalid when the user calls the C_Logout function or closes the last PKCS#11 session. The software purges the token objects from the software’s cache. A subsequent successful C_Login function brings in all the then-current token objects. Note that this login could be for a different user and thus bring in a different set of token objects. However, even if this login is for the same user, the token objects might not get the same handles as they had before.
The openCryptoki software is used as the PKCS#11 framework. See Appendix B for details on openCryptoki software.
If the Softtoken slot of the openCryptoki software is not installed on the system, you see only the Sun Crypto Accelerator 6000 (SCA) slot as follows:
If the Softtoken slot of the openCryptoki software is installed, you see the Sun Crypto Accelerator 6000 (SCA) slot first followed by the softtoken slot as follows:
The first part of the slot description is from the operating system. The second part denotes whether it is the Sun Crypto Accelerator 6000 (SCA) slot or the Softtoken slot (soft).
The Sun Crypto Accelerator 6000 (SCA) slot is a general PKCS#11 slot.
| Sun Crypto Accelerator 6000 Board User’s Guide for Version 1.1 | E39851-01 |
|
Copyright © 2013, Oracle and/or its affiliates. All rights reserved.