PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Design goals
Cryptoki was intended from the beginning as an interface between applications and all kinds of portable cryptographic devices, such as those based on smart cards, PCMCIA cards, and smart diskettes. There are already standards (de facto or official) for interfacing to these devices at some level. For instance, the mechanical characteristics and electrical connections are well-defined, as are the methods for supplying commands and receiving results. (See, for example, ISO 7816, or the PCMCIA specifications.)
What remained to be defined were particular commands for performing cryptography. It would not be enough simply to define command sets for each kind of device, as that would not solve the general problem of an application interface independent of the device. To do so is still a long-term goal, and would certainly contribute to interoperability. The primary goal of Cryptoki was a lower-level programming interface that abstracts the details of the devices, and presents to the application a common model of the cryptographic device, called a "cryptographic token" (or simply "token").
A secondary goal was resource sharing. As desktop multi-tasking operating systems become more popular, a single device should be shared between more than one application. In addition, an application should be able to interface to more than one device at a given time.
It is not the goal of Cryptoki to be a generic interface to cryptographic operations or security services, although one certainly could build such operations and services with the functions that Cryptoki provides. Thus, Cryptoki is intended to complement, not compete with such emerging and evolving interfaces as "Generic Security Services Application Programming Interface" (RFC's 1508 and 1509) and "Generic Cryptographic Service API" (GCS-API) from X/Open.
General model
Cryptoki's general model is illustrated in the following figure. The model begins with one or more applications that need to perform certain cryptographic operations, and ends with a cryptographic device, on which some or all of the operations are actually performed. A user may be associated with an application.
Cryptoki provides an interface to one or more cryptographic devices that are active in the system through a number of "slots". Each slot, which corresponds to a physical reader or other device interface, may contain a token. A token is "present in the slot" (typically) when a cryptographic device is present in the reader. Of course, since Cryptoki provides a logical view of slots and tokens, there may be other physical interpretations. It is possible that multiple slots may share the same physical reader. The point is that a system has some number of slots and applications can connect to all those tokens.
A cryptographic device can perform some cryptographic operations, following a certain command set; these commands are typically passed through standard device drivers, for instance PCMCIA card services or socket services. Cryptoki makes the cryptographic device look logically like every other device, regardless of the implementation technology. Thus the application need not interface directly to the device drivers (or even know which ones are involved); Cryptoki hides these details. Indeed, the "device" may be implemented entirely in software, for instance as a process running on a server; no hardware is necessary.
Cryptoki would likely be implemented as a library supporting the functions in the interface, and applications would be linked to the library. An application may be linked to Cryptoki directly, or Cryptoki could be a so-called "shared" library (or dynamic link library), in which case the application would link the library dynamically. Shared libraries are fairly straightforward in operating systems such as Microsoft WindowsTM, OS/2TM, and can be achieved, without too much difficulty, in UnixTM and DOS systems.
The dynamic approach would certainly have advantages as new libraries are made available, but from a security perspective, there are some drawbacks. In particular, if the library is easily replaced, then there is the possibility that an attacker can substitute a rogue library that intercepts a user's PIN. From a security perspective, direct linking would probably be better. However, whether the linking is direct or dynamic, the programming interface between the application and Cryptoki remains the same.
The kinds of devices and capabilities supported will depend on the particular Cryptoki library. This standard only specifies the interface to the library, not its features. In particular, not all libraries will support all the mechanisms (algorithms) defined in this interface (since not all tokens are expected to support all the mechanisms), and libraries will likely support only a subset of all the kinds of cryptographic devices that are available. (The more kinds, the better, of course, and it is anticipated that libraries will be developed supporting multiple kinds of token, not just those from a single vendor.) It is expected that as applications are developed that interface to Cryptoki, standard library and token "profiles" will emerge.
Logical view of a token
Cryptoki's logical view of a token is a device that stores objects and can perform cryptographic functions. Cryptoki defines three classes of object: Data, Certificates, and Keys. A data object is defined by an application. A certificate object stores a public-key certificate. A key object stores an encryption key. The encryption key be may a public key (RSA, DSA or Diffie-Hellman), a private key (RSA, DSA or Diffie-Hellman) or a secret key (RC2, RC4, DES, etc.). This view is illustrated in the following figure. The key types given are those supported for this version of Cryptoki; other key types may well be added in future versions.
Objects are also classified according to their lifetime and visibility. "Token objects" are visible to all applications connected to the token, and remain in the token after the "session" or connection between an application and the token is closed. "Session objects" are visible only to the application that creates them, and are destroyed automatically when the session is closed.
Further classification defines access requirements. "Public objects" are visible to all applications that have a session with the token. "Private objects" are visible to an application only after a user has been authenticated to the token by a PIN.
A token can create and destroy objects, manipulate them, and search for them. It can also perform cryptographic functions on objects. It is possible for the token to perform the cryptographic operations in parallel with the application, assuming the underlying device has its own processor. In addition, a token may have an internal random number generator.
It is important to distinguish between the logical view of a token and the actual implementation, because not all cryptographic devices will have this concept of "objects," or be able to perform every kind of cryptographic function. Many devices will simply have fixed storage places for keys of a fixed algorithm, and be able to do a limited set of operations. Cryptoki's role is to translate this into the logical view, mapping attributes to fixed storage elements and so on. Not all Cryptoki libraries and tokens need to support every object type. It is expected that standard "profiles" will be developed, specifying sets of algorithms to be supported.
"Attributes" are characteristics that distinguish an instance of an object. In Cryptoki, there are general attributes, such as whether the object is private or public. There are also attributes particular to an object, such as a modulus or exponent for RSA keys.
Users
This version of Cryptoki recognizes two token user types. One type is a Security Officer (SO). The other type is the normal user. Both types of user must be authenticated with a PIN to the token before any access to private objects is allowed. Some tokens may require that a user be authenticated before any cryptographic function can be performed on the token, whether or not it involves private objects. The role of the SO is to initialize a token and to set the normal user's PIN, and possibly manipulate some public objects. A normal user cannot log in until the SO has set the user's PIN.
Other than the support for two types of user, Cryptoki does not address the relationship between the SO and a community of users. In particular, the SO and the User may be the same person or may be different, but such matters are outside the scope of this standard.
With respect to PINs, Cryptoki assumes only that they are variable-length character strings from the set in Table 4 -3. Any translation to the device's requirements is left to the Cryptoki library. The following items are beyond the scope of Cryptoki:
Cryptoki requires that an application "open a session" with a token before the application has access to the token's objects and functions. The session provides the logical connection between the application and the token. A session can be a read/write (R/W) session or a read-only (R/O) session. Read/write and read-only refer to the access to token objects, not to session objects. In both session types, an application can create, read, write and destroy session objects, and read token objects. However, only in a read/write session can an application create, write and destroy token objects.
After a session is opened, the application has access to the token's "public" objects. To gain access to the token's "private" objects, a user must log in and be authenticated.
Cryptoki supports multiple sessions on multiple tokens. An application may have one or more sessions with one or more tokens. A token may have multiple sessions with one or more applications. Some tokens may allow only one read/write session at any given time.
An open session can be in one of several states. The session state determines allowable access to objects and functions that can be performed on them. The session states are described in the next two sections.
Read-only session states
A read-only session can be in one of two states, as illustrated in the following figure. When the session is opened, it is in the "R/O Public Session" state. Only the normal user may open a read-only session.
Table 5-1, Read-Only Session States
| State | Description |
| R/O Public Session | The application has opened a read-only session. The application has read-only access to public objects on the token. |
| R/O User Functions | The normal user has been authenticated to the token. The application has read-only access to public and private objects on the token. |
Read/write session states
A read/write session can be in one of three states, as illustrated in the following figure. When the session is opened, it is in the "R/W Public Session" state.
Table 5-2, Read/Write Session States
| State | Description |
| R/W Public Session | The application has opened a read/write session. The application has read/write access to public objects on the token. |
| R/W SO Functions | The Security Officer has been authenticated to the token. The application has read/write access only to public objects on the token, not to private objects. The SO can set the normal user's PIN. |
| R/W User Functions | The normal user has been authenticated to the token. The application has read/write access to public and private objects on the token. |
Session events
Session events cause the session state to change. The following table describes the events.
| Event | Occurs when... |
| Log In SO | the SO is authenticated to the token. |
| Log In User | the normal user is authenticated to the token. |
| Log Out | the application logs out the current user. |
| Close Session | the application closes the session or an application closes all sessions. |
| Device Removed | the device underlying the token has been removed from its slot. |
Note that when the device is removed, the user is automatically logged out. However, the session remains open. If the device is reinserted, the application can log in the user again without opening a new session.
Function overview
The Cryptoki API consists of a number of functions, spanning slot and token management through object management, as well as cryptographic functions. These functions are presented in the following table.
Table 5-4, Summary of Cryptoki Functions
| Category | Function | Description |
| General | C_Initialize | initializes Cryptoki |
| purpose | C_GetInfo | obtains general information about Cryptoki |
| Slot and | C_GetSlotList | obtains a list of slots in the system |
| token | C_GetSlotInfo | obtains information about a particular slot |
| management | C_GetTokenInfo | obtains information about a particular token |
| C_GetMechansimList | obtains a list of mechanisms supported by a token | |
| C_GetMechanismInfo | obtains information about a particular mechanism | |
| C_InitToken | initializes a token | |
| C_InitPIN | initializes the normal user's PIN | |
| C_SetPIN | modifies the PIN of the current user | |
| Session management | C_OpenSession | opens a connection or "session" between an application and a particular token |
| C_CloseSession | closes a session | |
| C_CloseAllSessions | closes all sessions with a token | |
| C_GetSessionInfo | obtains information about the session | |
| C_Login | logs into a token | |
| C_Logout | logs out from a token | |
| Object | C_CreateObject | creates an object |
| management | C_CopyObject | creates a copy of an object |
| C_DestroyObject | destroys an object | |
| C_GetObjectSize | obtains the size of an object in bytes | |
| C_GetAttributeValue | obtains an attribute value of an object | |
| C_SetAttributeValue | modifies an attribute value of an object | |
| C_FindObjectsInit | initializes an object search operation | |
| C_FindObjects | continues an object search operation | |
| Encryption | C_EncryptInit | initializes an encryption operation |
| and | C_Encrypt | encrypts single-part data |
| decryption | C_EncryptUpdate | continues a multiple-part encryption operation |
| C_EncryptFinal | finishes a multiple-part encryption operation | |
| C_DecryptInit | initializes a decryption operation | |
| C_Decrypt | decrypts single-part encrypted data | |
| C_DecryptUpdate | continues a multiple-part decryption operation | |
| C_DecryptFinal | finishes a multiple-part decryption operation | |
| Message | C_DigestInit | initializes a message-digesting operation |
| digesting | C_Digest | digests single-part data |
| C_DigestUpdate | continues a multiple-part digesting operation | |
| C_DigestFinal | finishes a multiple-part digesting operation | |
| Signature | C_SignInit | initializes a signature operation |
| and | C_Sign | signs single-part data |
| verification | C_SignUpdate | continues a multiple-part signature operation |
| C_SignFinal | finishes a multiple-part signature operation | |
| C_SignRecoverInit | initializes a signature operation, where the data can be recovered from the signature | |
| C_SignRecover | signs single-part data, where the data can be recovered from the signature | |
| C_VerifyInit | initializes a verification operation | |
| C_Verify | verifies a signature on single-part data | |
| C_VerifyUpdate | continues a multiple-part verification operation | |
| C_VerifyFinal | finishes a multiple-part verification operation | |
| C_VerifyRecoverInit | initializes a verification operation where the data is recovered from the signature | |
| C_VerifyRecover | verifies a signature on single-part data, where the data is recovered from the signature | |
| Key | C_GenerateKey | generates a secret key |
| management | C_GenerateKeyPair | generates a public-key/private-key pair |
| C_WrapKey | wraps (encrypts) a key | |
| C_UnwrapKey | unwraps (decrypts) a key | |
| C_DeriveKey | derives a key from a base key | |
| Random number | C_SeedRandom | mixes in additional seed material to the random number generator |
| generation | C_GenerateRandom | generates random data |
| Function management | C_GetFunctionStatus | obtains updated status of a function running in parallel with the application |
| C_CancelFunction | cancels a function running in parallel with the application | |
| Callbacks | Notify | processes notifications from Cryptoki |
Functions in the "Encryption and decryption," "Message digesting," "Signature and verification," and "Key management" categories may run in parallel with the application if the token has the capability and the session is opened in this mode.