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:
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 (libpkcs11.so). 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.
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:
Message encryption and message digest
Message authentication codes (MACs)
Digital signing
Application programmer interfaces (APIs) for accessing cryptographic services
Service provider interfaces (SPIs) for providing cryptographic services
An administration command for managing cryptographic resources
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.
The components of the cryptographic framework are described as follows.
libpkcs11.so – The framework provides access through the RSA Security Inc. PKCS#11 Cryptographic Token Interface (Cryptoki). Applications need to link to the libpkcs11.so library, which implements the RSA PKCS#11 v2.11 of the standard.
Pluggable interface – The pluggable interface is the service provider interface (SPI) for PKCS #11 cryptographic services that are provided by Sun Microsystems, Inc. and third-party developers. Providers are user-level libraries. Providers are implemented through encryption services that are available from either hardware or software.
pkcs11_softtoken.so – A private shared object that contains user-level cryptographic mechanisms that are provided by Sun Microsystems, Inc. The pkcs11_softtoken(5) library implements the RSA PKCS#11 v2.11 of the standard.
pkcs11_kernel.so – The private shared object used to access kernel-level cryptographic mechanisms. pkcs11_kernel(5) implements the RSA PKCS#11 v2.11 specification. pkcs11_kernel.so offers a PKCS#11 user interface for cryptographic services that are plugged into the kernel's service provider interface.
/dev/crypto pseudo device driver – The private pseudo device driver for using kernel-level cryptographic mechanisms. This information is provided to avoid inadvertent deletion of the pseudo device driver.
Scheduler / load balancer – The kernel software that is responsible for coordinating use, load balancing, and dispatching of the cryptographic service requests.
Kernel programmer interface – The interface for kernel-level consumers of cryptographic services. The IPSec protocol and the kerberos GSS mechanism are typical cryptographic consumers.
This interface is only available through a special contract with Sun Microsystems, Inc. Send email to solaris-crypto-api@sun.com for more information.
Service provider interface – The SPI for providers of kernel-level cryptographic services. These services can be implemented on either hardware or software. To use the SPI, a provider must import special routines from the Oracle Solaris kernel. These routines enable modules and device drivers to register and remove services. The routines also notify the framework about changes in state. The framework also requires that providers export certain routines. The exported routines enable consumers and other components of the cryptographic framework to send requests to the provider.
Sun HW and SW cryptographic providers – Kernel-level cryptographic services that are provided by Sun Microsystems, Inc. HW refers to hardware cryptographic services such as accelerator boards. SW refers to kernel modules that provide cryptographic services, such as an implementation of a cryptographic algorithm.
Kernel cryptographic framework daemon – The private daemon that is responsible for managing system resources for cryptographic operations. The daemon is also responsible for verifying cryptographic providers.
Module verification library – A private library used to verify the integrity and authenticity of all binaries that the Oracle Solaris cryptographic framework is importing.
elfsign – A utility offered to third-party providers of cryptographic services. elfsign is used to request certificates from Sun. elfsign also enables providers to actually sign the binaries, that is, elf objects that plug into the Oracle Solaris cryptographic framework.
/dev/cryptoadm pseudo device driver – The private pseudo device driver used by cryptoadm(1M) for administering kernel-level cryptographic mechanisms. This information is provided to avoid inadvertent deletion of the pseudo device driver.
cryptoadm – A user-level command for administrators to manage cryptographic services. A typical cryptoadm task is listing cryptographic providers and their capabilities. Disabling and enabling cryptographic mechanisms according to security policy is also performed with cryptoadm.
This section describes the requirements to develop the four types of applications that can plug into the Oracle Solaris cryptographic framework.
To develop a user-level consumer, do all of the following:
Include <security/cryptoki.h>.
Make all calls through the PKCS #11 interfaces only.
Link with libpkcs11.so.
Libraries should not call the C_Finalize() function.
See Chapter 9, Writing User–Level Cryptographic Applications and Providers for more information.
To develop a user-level provider, do all of the following:
Design the provider to stand alone. Although the provider shared object need not be a full-fledged library to which applications link, all necessary symbols must exist in the provider. Assume that the provider is to be opened by dlopen(3C) in RTLD_GROUP and RTLD_NOW mode.
Create a PKCS #11 Cryptoki implementation in a shared object. This shared object should include necessary symbols rather than depend on consumer applications.
It is highly recommended though not required to provide a _fini() routine for data cleanup. This method is required to avoid collisions between C_Finalize() calls when an application or shared library loads libpkcs11 and other provider libraries concurrently. See Avoiding Data Cleanup Collisions in User-Level Providers.
Apply for a certificate from Sun Microsystems, Inc. See To Request a Certificate for Signing a Provider.
Use the certificate with elfsign to sign the binary. See To Sign a Provider.
Package the shared object according to Sun conventions. See Appendix F, Packaging and Signing Cryptographic Providers.
To develop a kernel-level consumer, do all of the following:
Include <sys/crypto/common.h> and <sys/crypto/api.h>.
Make all calls through the kernel programming interface.
To develop a kernel-level provider, do all of the following:
Include <sys/crypto/common.h> and <sys/crypto/api.h>.
Import required routines for registering, unregistering, and providing status.
Export required routines to provide entry points for kernel cryptographic framework.
Export data structure with descriptions of supported algorithms.
Create loadable kernel module.
Apply for a certificate from Sun Microsystems, Inc. See To Request a Certificate for Signing a Provider.
Use the certificate with elfsign to sign the binary. See To Sign a Provider.
Package the kernel module according to Sun conventions. See Appendix F, Packaging and Signing Cryptographic 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.
#pragma fini(pkcs11_fini) static void pkcs11_fini(); /* [... (other library code omitted)] */ static void pkcs11_fini() { (void) pthread_mutex_lock(&pkcs11mutex); /* If CRYPTOKI is not initialized, do not clean up */ if (!initialized) { (void) pthread_mutex_unlock(&pkcs11mutex); return; } (void) finalize_routine(NULL_PTR); (void) pthread_mutex_unlock(&pkcs11mutex); }