| Sun Crypto Accelerator 4000 Board Version 1.1 Installation and User's Guide |    
|
| Sun Crypto Accelerator 4000 Board Version 1.1 Installation and User's Guide |
|
| C H A P T E R 8 |
|
PKCS#11 Interface |
This chapter describes the board's implementation of the PKCS#11 interface and assumes that the Sun Crypto Accelerator 4000 software is installed in the default locations. This chapter also assumes you have familiarity with the PKCS#11 interface. Information about the PKCS#11 standard and original copies of the header files pkcs11.h, pkcs11f.h, and pkcs11t.h., are available at: http://www.rsasecurity.com/rsalabs/PKCS
This chapter includes the following sections:
The Sun Crypto Accelerator 4000 board and associated software provide a PKCS#11 interface. All the PKCS#11 functions necessary for most applications are provided in the Sun Crypto Accelerator 4000 software.
PKCS#11 was designed for a single-user system. The Solaris operating system is a multi-user system, and must deal with multiple concurrent mutually-distrusting users. To accommodate this, the board has added provision for identifying and authenticating multiple users without extending PKCS#11. Every PKCS#11 function that accepts a secret PIN must be given a string of the form username:password (See TABLE 5-1). This PIN structure typically propagates up through applications, although a few applications written specifically for the board might ask for the username and secret part separately.
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.
The vcaadm security officer (SO) is not related to the UNIX superuser. Additionally, a board user's userid, which is created by the SO with vcaadm, is not related to any UNIX username or ID.
PKCS#11 has distinct notions of slots and tokens. Tokens are similar to smart cards, and plug into slots. In the Sun Crypto Accelerator 4000 system, there is no distinction between slots and tokens. This guide generally uses the term token; however, applications and other documentation might use the term slot.
Each board supports up to one keystore. The SO gives each keystore a name with vcaadm. Each keystore is presented by the board as a PKCS#11 token, with the token label being the name of the associated keystore, space-padded to 32 characters. Multiple boards may support a single keystore for high-availability.
In addition, there is one special token with the label SUNW acceleration only. This token cannot store any persistent keys, and applications cannot log into this token. Requests submitted to this token are distributed over all available boards.
Many applications display a list of tokens--generally tokens are identified by the PKCS#11 token label. (The token label is the space-padded name of the associated keystore assigned by the SO.)
The Sun Crypto Accelerator 4000 system is administered using the vcaadm utility (See Chapter 4). The SO names the keystore and creates user accounts, giving each account an initial password. The SO also controls whether or not the board operates in FIPS mode (See PKCS#11 and FIPS Mode).
The board supports many PKCS#11 mechanisms. Most of the mechanisms are unconditionally available. However the administrator has some control over the presentation of the following mechanisms:
These mechanisms are always presented by the acceleration-only token. They are presented by tokens with keystores only if the /etc/opt/SUNWconn/cryptov2/sslreg is present. To create this file, type the following command as superuser:
Restart the applications for this change to take affect.
Network Security Services (NSS) recognizes when these mechanisms are available. When the mechanisms are provided, NSS makes many calls to C_DigestUpdate with tiny buffers, which causes the performance to degrade. For this reason, these mechanisms are not provided by default.
The default location for the PKCS#11 library is: /opt/SUNWconn/cryptov2/lib/libvpkcs11.so
Most applications have a configuration file or database, sometimes accessed with a GUI, that contains the location of the PKCS#11 library. Using an editor or the GUI, enter the above value for the default location.
When a key has the CKA_SENSITIVE attribute, operations involving that key are restricted to hardware. However, not all operations and all types of keys are supported by the hardware. If an application requests an operation that cannot be done in hardware, and the key's CKA_SENSITIVE attribute is true, the operation will fail. The precise rules regarding what combinations keys, operations, and mechanisms are available is described in detail in Hardware Acceleration and Sensitive Keys. If your application will not run because of these rules, you might be able to configure it to not mark its keys as sensitive.
Whether or not the SSL... and TLS... mechanisms are presented is controlled by the administrator. If the application requires these mechanisms, or you want to experiment with the performance effect of having these mechanisms available, see Administering the Board to Use PKCS#11.
If the board is in FIPS mode, it will provide only mechanisms that are FIPS-approved (See PKCS#11 and FIPS Mode).
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, RC2, and RC4 are not FIPS-approved. However, because the FIPS regulations apply only to the hardware, the software will continue to make available all the mechanisms that the software normally provides.
The main difference incurred when operating in FIPS mode is that non-FIPS-approved operations will be done only in software, which has two consequences:
The board chooses where to execute operations based on the capability of the hardware, on security requirements, and on performance.
PKCS#11 specifies many key types and mechanisms, not all of which are entirely supported in the hardware. When an application requests a combination of operation, key, and mechanism that is not supported entirely in hardware, it may be executed partially in software and partially in hardware, or it may be executed entirely in software.
When a key's CKA_SENSITIVE attribute is true, any operation that uses it must be executed securely, that is, with no key material leaving the hardware. If the hardware is not capable of securely executing the operation, it fails. Alternately, when the key's CKA_SENSITIVE attribute is false, the board chooses between hardware and software based on performance. This section describes the rules used to choose between hardware, software, and failing the operation.
For convenience, the following sets of keys and mechanisms are defined:
For any operation to execute securely in the hardware, the key must be in the hardware_key_set and the mechanism must be in the hardware_mechanism_set. If the key is in the hardware_key_set but the mechanism is not in the hardware_mechanism_set, the operation may be accelerated by hardware, but with software assistance.
C_DeriveKey may be accelerated in hardware, but requires the assistance of software and thus is not hardware-level secure.
The following table describes if and where operations involving keys are performed:
|
Hardware for RSA, DSA, and large buffers; software otherwise |
||
|
Hardware and software for RSA, DSA, and large buffers; software otherwise |
||
C_WrapKey and C_UnwrapKey involve two operations on two keys. For the C_Wrap key, there is an encode operation that encodes the wrapped key, followed by an encrypt operation that encrypts the encoded value using the wrapping key. C_UnwrapKey does the reverse, but with decrypt and decode.
If the wrapped key is an RSA or DSA key and the wrapping mechanism is the hardware_wrap_mechanism_set, both the encoding and encryption steps are done in hardware. The operation will be hardware-level secure for both keys.
If any of the conditions above are not satisfied, the encoding step will be done in software. The operation will be not be hardware-level secure for the wrapped key. The encryption step will be treated the same as a C_Encrypt operation using the wrapping key and the mechanism. Refer to TABLE 8-1.
The various cases are summarized in the following table:
C_Digest assembles the entire buffer in host memory. C_DigestFinal sends the entire buffer to hardware if the buffer is large, but does not exceed 65532 bytes. Otherwise the entire buffer is processed in software.
C_DigestKey brings the key material into host memory and then treats it just like ordinary data, which is then processed with C_DigestUpdate. It will fail if the key's CKA_SENSITIVE attribute is true.
The necessary header files are in /opt/SUNWconn/cryptov2/include; add this directory to the include path and include cryptoki.h. The lower-level include files, pkcs11.h, pkcs11f.h, and pkcs11t.h are available in the Sun Crypto Accelerator 4000 software. These files are identical to those available at the PKCS#11 web site (http://www.rsasecurity.com/rsalabs/PKCS). The pkcs11_preamble.h file is available in the include directory and must be included before any of the lower level files.
The pkcs11 library is: /opt/SUNWconn/cryptov2/lib/libvpkcs11.so.
The Sun Crypto Accelerator 4000 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:
cc [flags] files... -L /opt/SUNWconn/cryptov2/lib \ -R /opt/SUNWconn/cryptov2/lib -l vpkcs11 [other libraries...] |
The code should invoke functions directly as in the following example:
When dynamically linking use the following (shown with error handling elided):
The code should invoke functions indirectly, as follows:
The Sun Crypto Accelerator 4000 software imposes very few arbitrary limits. Most resources are limited only by host memory. The maximum number of tokens, including the acceleration-only token, is 1024.
To prevent a denial of service attack by a faulty or malicious program consuming excessive kernel memory, the software limits the amount of kernel memory any one Solaris user (not process) may consume to no more than 16 Mbytes. This limit is not configurable.
You can avoid kernel memory exhaustion problems by observing the following recommendations:
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 persistent 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 volatile (session) objects is limited by virtual memory only. Persistent objects must all fit in the RAM on the board, but this is not a limitation for any practical use. Consistent with this concept, 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.
Only a limited implementation of C_GetOperationState and its companion function C_SetOperationState is provided. C_GetOperationState succeeds only when the operation is C_Digest and the size of the accumulated input data does not exceed 65532 bytes.
The tokens provided by the Sun Crypto Accelerator 4000 system are considered nonremovable. Thus the CKF_REMOVABLE_DEVICE flag returned by CK_GetSlotInfo is false.
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 with CKR_RANDOM_SEED_NOT_SUPPORTED.
Functions with an implementation that depends on critical fields being in host memory in the clear will fail when they involve a key that has been created with the CKA_SENSITIVE attribute set to true. The precise rules are as follows:
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 if a template contains the same attribute more than once, the implementation simply uses the last value. Attributes not associated with the key type are simply ignored. Not all invalid attributes are detected.
The CKA_LOCAL, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE attributes are not implemented.
The error codes returned by the software are not always 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, important state has probably not been properly saved, and attempting to continue, except by calling C_Finalize, may be futile.
To reduce overhead, the software's implementation of C_EncryptInit and similar functions sometimes defers sending the key to the board until there is actual data to encrypt. A consequence of this deferral is that certain errors that PKCS#11 declares should be reported by C_EncryptInit (and similar functions) are actually reported on the first subsequent call to C_EncryptUpdate (and similar functions).
The mechanisms known by the following PKCS#11 designators are available in the Sun Crypto Accelerator 4000 software. The CKM_SSL3... and CKM_TLS... mechanisms, although shown in the list, are available on tokens with keystores only if the file /etc/opt/SUNWconn/cryptov2/sslreg is present (See Administering the Board to Use PKCS#11).
RSA, DSA, and Diffie-Hellman keys have the following maximum key sizes:
Do not assume that object handles or session handles are small integers or are sequentially allocated. These handles may be any unsigned long.
The mutex callback function pointers that can be passed to C_Initialize are ignored.
In many cases, operations on small amounts of data are processed by the host processor rather than the board because the cost of sending the operation to the board exceeds the cost of doing it in the host. However, all operations involving objects with the CKA_SENSITIVE attribute set to true are done in the board.
If the accumulated size of all C_DigestUpdate buffers exceeds 65532 bytes, the digesting is processed by software in the host. The same characteristic applies to C_Digest. So both small and very large amounts of data are processed by software.
Information about persistent objects is brought into a process when the user successfully executes the C_Login function and it remains cached. Subsequent creation, deletion, or modification of persistent objects by another process might not be observed. Operations that take place in the board will use the current state of the key. (Operations are performed in the board if the board is capable and the key is sensitive, or the board is capable and the buffer is large enough to justify it.) All other cases, plus C_FindObjects functions, are processed in software with the cached state of the key.
|
Caution - Do not depend on the above key-caching behavior remaining unchanged in future releases. |
As required by the PKCS#11 standard, all persistent 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.
| Sun Crypto Accelerator 4000 Board Version 1.1 Installation and User's Guide | 817-3693-10 |
|
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.