Developer's Guide to Oracle Solaris Security

Chapter 8 Introduction to the Oracle Solaris Cryptographic Framework

The Oracle Solaris cryptographic framework is an architecture that enables applications in the Oracle Solaris operating system to use or provide cryptographic services. All interactions with the framework are based on the RSA Security Inc. PKCS#11 Cryptographic Token Interface (Cryptoki). PKCS#11 is a product by RSA Laboratories, the research arm of RSA Security Inc.

This chapter presents the following topics on the Oracle Solaris cryptographic framework:

Oracle Solaris Cryptography Terminology

An application, library, or kernel module that obtains cryptographic services is called a consumer. An application that provides cryptographic services to consumers through the framework is referred to as a provider and also as a plug–in. The software that implements a cryptographic operation is called a mechanism. A mechanism is not just the algorithm but includes the way in which the algorithm is to be applied. For example, the DES algorithm when applied to authentication is considered a separate mechanism. DES when applied to block-by-block encryption would be a different mechanism.

A token is the abstraction of a device that can perform cryptography. In addition, tokens can store information for use in cryptographic operations. A single token can support one or more mechanisms. Tokens can represent hardware, as in an accelerator board. Tokens that represent pure software are referred to as soft tokens. A token can be plugged into a slot, which continues the physical metaphor. A slot is the connecting point for applications that use cryptographic services.

In addition to specific slots for providers, the Oracle Solaris implementation provides a special slot called the metaslot. The metaslot is a component of the Oracle Solaris cryptographic framework library ( The metaslot serves as a single virtual slot with the combined capabilities of all tokens and slots that have been installed in the framework. Effectively, the metaslot enables an application to transparently connect with any available cryptographic service through a single slot. When an application requests a cryptographic service, the metaslot points to the most appropriate slot, which simplifies the process of selecting a slot. In some cases, a different slot might be required, in which case the application must perform a separate search explicitly. The metaslot is automatically enabled and can only be disabled through explicit action by the system administrator.

A session is a connection between an application that use cryptographic services and a token. The PKCS #11 standard uses two kinds of objects: token objects and session objects. Session objects are ephemeral, that is, objects that last only for the duration of a session. Objects that persist beyond the length of a session are referred to as token objects.

The default location for token objects is $HOME/.sunw/pkcs11_softtoken. Alternatively, token objects can be stored in $SOFTTOKEN_DIR/pkcs11_softtoken. Private token objects are protected by personal identification numbers (PIN). To create or change a token object requires that the user be authenticated, unless the user is accessing a private token object.

Overview of the Cryptographic Framework

The cryptographic framework is the portion of the Oracle Solaris OS that provides cryptographic services from Sun Microsystems, Inc. and from third-party suppliers. The framework provides various services:

The following figure provides an overview of the cryptographic framework. The light gray shading in the figure indicates the user-level portion of the cryptographic framework. The dark gray shading represents the kernel-level portion of the framework. Private software is indicated by a background with diagonal striping.

Figure 8–1 Overview of the Oracle Solaris Cryptographic Framework

Diagram shows major elements in the Oracle Solaris cryptographic

Components of the Cryptographic Framework

The components of the cryptographic framework are described as follows.

What Cryptography Developers Need to Know

This section describes the requirements to develop the four types of applications that can plug into the Oracle Solaris cryptographic framework.

Requirements for Developers of User-Level Consumers

To develop a user-level consumer, do all of the following:

See Chapter 9, Writing User–Level Cryptographic Applications and Providers for more information.

Requirements for Developers of User-Level Providers

To develop a user-level provider, do all of the following:

Requirements for Developers of Kernel-Level Consumers

To develop a kernel-level consumer, do all of the following:

Requirements for Developers of Kernel-Level Providers

To develop a kernel-level provider, do all of the following:

Avoiding Data Cleanup Collisions in User-Level Providers

User-level libraries that plug into the cryptographic framework should supply a _fini() function. The _fini() function is called by the loader when the library is unloaded. The _fini() function is required to ensure that all cleanup is done correctly at the right time. Libraries that use libpkcs11 are not supposed to call C_Finalize(), because libpkcs11 is a shared library that could potentially be in use by the application.

To supply a _fini() function, you need to create a .fini section in the program data section of a relocatable object. The .fini section provides a runtime termination code block. See Linker and Libraries Guide. The following code sample demonstrates how to design a .fini section.

Example 8–1 Supplying _fini() to PKCS #11 Libraries

#pragma fini(pkcs11_fini)
static void pkcs11_fini();

/* [... (other library code omitted)] */

static void
        (void) pthread_mutex_lock(&pkcs11mutex);
        /* If CRYPTOKI is not initialized, do not clean up */
        if (!initialized) {
                (void) pthread_mutex_unlock(&pkcs11mutex);
        (void) finalize_routine(NULL_PTR);
        (void) pthread_mutex_unlock(&pkcs11mutex);