| Sun Crypto Accelerator 4000 Board Version 2.0 Installation and User's Guide |    
|
| Sun Crypto Accelerator 4000 Board Version 2.0 Installation and User's Guide |
|
| C H A P T E R 5 |
|
Building PKCS#11 Applications for Use With the Sun Crypto Accelerator 4000 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. This chapter includes the following sections:
The Sun Crypto Accelerator 4000 board is registered in the Solaris Cryptographic Framework as a hardware provider. Thus, the board can be administered using the system commands. Refer to Solaris Cryptographic Services section in the Solaris 10 System Administration Guide: Security Services document.
The Solaris Cryptographic Framework provides a PKCS#11 library through which the Sun Crypto Accelerator 4000 board is accessed. By default, the library is located at /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 vcaadm utility. See Chapter 4.
When the board is first initialized, vcaadm prompts you to set up a security officer account. This security officer is not related to the PKCS#11 security officer, and cannot authenticate to a board through the PKCS#11 interface.
Also during board initialization, vcaadm 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 board is initialized, the security officer can create one or more users using the vcaadm utility. Users created by the security officer authenticate to a board 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 Solaris PKCS#11 library.
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 4000 board are made up of the keystore name padded with spaces.
Sun Metaslot uses all of the cryptographic engines on the system, including the Sun Crypto Accelerator 4000; thus, it provides the maximum functionality. By default, Sun Metaslot uses the Solaris Softtoken keystore; however it can be configured to use the Sun Crypto Accelerator 4000 keystore. See Sun Metaslot.
Hardware slot is a slot which is bound to and dedicated to a hardware device. There should be one hardware slot per Sun Crypto Accelerator 4000 board. The hardware slot's description and the token label for board are in the following format: vca/instance Crypto Accel 2.0. This slot is useful for diagnosis since it is directly associated with a board.
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 4000 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 crypto 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 4000 board for cryptographic acceleration along with all other cryptographic providers available on the system. Sun Metaslot uses the board for the mechanisms it supports, and it uses other slots including the Solaris software implementation for the mechanisms not supported by the board. 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 Solaris Softtoken keystore. To access the Sun Crypto Accelerator 4000 keystore through Sun Metaslot, you must use one of the following configurations.
Enter the following command to use the Sun Crypto Accelerator 4000 keystore. For the example in this section, ks is the name of the Sun Crypto Accelerator 4000 keystore.
This command forces a global change throughout the system, which causes all applications on the system to use the Sun Crypto Accelerator 4000 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 4000 keystore.
The environment variable overwrites the system-wide configuration.
Sun Metaslot supports failover by automatically migrating keys from the Sun Crypto Accelerator 4000 keystore to other slots. By doing so, the keys securely stored on the board may 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 4000 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 non-sensitive keys and sensitive session keys will still be 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.
The Hardware slot is dedicated to a single board; thus, it does not allow hardware redundancy or load balancing. For the typical application, either the Keystore slot or Sun Metaslot is preferred for this reason. This slot, however, is useful for diagnosis. Like the Keystore slot, both sensitive session keys and sensitive token keys are kept secure on the board.
When put in FIPS mode by the SO (using vcaadm), the Sun Crypto Accelerator 4000 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/dmvp
Operating the board in FIPS mode causes the following changes in the board's operation:
FIPS mode applies only to the Sun Crypto Accelerator 4000 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 will still be 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://www.rsasecurity.com/rsalabs/PKCS).
The PKCS#11 libraries are: /usr/lib/libpkcs11.so (32-bit mode) and /usr/lib/sparcv9/libpkcs11.so (64-bit mode)
The 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 deletable without authentication. Because the users known by the Sun Crypto Accelerator 4000 software are unrelated to 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 4000 board can only operate SHA-1 and MD5 in a single part and the PKCS#11 interface requires both single part and multi part 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.
Since AES has become a standard algorithm for secure bulk encryption, the Sun Crypto Accelerator 4000 board supports the CKM_AES_CBC mechanism with sensitive keys. AES support is implemented in the firmware and provides less performance than supported by the host system. AES is only intended to be used by applications that require the added security of having keys kept in the Sun Crypto Accelerator 4000 hardware. Thus, unless you are concerned about the security of the AES keys, AES algorithm for the board should be turned off. (See Chapter 3)
The tokens provided by the Sun Crypto Accelerator 4000 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 4000 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 4000 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 4000 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 4000 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 4000 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 log in 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.
| Sun Crypto Accelerator 4000 Board Version 2.0 Installation and User's Guide | 817-6972-10 |
|
Copyright © 2004, Sun Microsystems, Inc. All Rights Reserved.