kCF Functional Spec

NOTE: Not all the links work, we are in the process of transitioning this onto this page

Kernel Cryptographic Framework Functional Specification

Contents

1. Overview
2. High Level Design
   1. Requirements and Design Considerations
   2. Architecture
   3. Interfaces
      1. Kernel Programming interface
      2. Provider Interface
      3. Administrative Interface
      4. Interface to user-level libraries.
3. Detailed Design
   1. Common data structures
   2. Provider tables and mechanism chains
   3. Scheduling and load balancing
   4. Sessions and object management
   5. Memory management
   6. Observability
   7. Extensibility
4. Appendix A: Glossary
5. Appendix B: List of attached documents.

1. Overview

 This document contains the functional specifications of the Solaris kernel cryptographic framework project, PSARC case 2001/553.

 The project is part of the Public Key Enabling program for Solaris (PSARC 2001/550). It delivers a framework for the cryptographic services in the Solaris Kernel. It exposes 1) a programming interface for kernel-level  consumers and a system call interface for user libraries enabling both sides to access the cryptographic services in the Solaris kernel,  2) a service provider interface for Sun and third party pluggable kernel cryptographic providers. An administrative interface is also provided as part of this project.

 This project imports  iterfaces from and exports to its twin project the User-land Cryptographic framework (PSARC case 2001/488).

The intended audience of this document is the Sun engineers, architects, and technical writers community. These specifications have references to more detailed design documents and man pages attached here as part of the project's ARC materials. Third party developers will use the detailed programming and provider interfaces, attached here, and  expected to be included in the Solaris answer book.

2. High Level Design

2.1 Requirements and Design considerations

 The programming and provider interfaces of this framework have to accommodate the following needs:

• The environmental constraints of the calling code (consumer) - Calls come from kernel clients, that can be running in (1) an interrupt context, (2) in the context of a user process (kernel thread that has an LWP) or (3) in the context of a detached kernel thread (e.g. a taskq scheduler).
• The mode of operation of the providers that will handle the operations- The functions exported by a software based provider will typically execute in a synchronous way, without surrendering the CPU. Hardware based providers usually operate in an asynchronous mode where an operation involves a programmed I/O of the hardware and possibly an interrupt upon completion.
• The parallelism constraints- The whole kernel is one protected address space, where several threads running on different CPUs can be attempting to simultaneously operate on the same data.
• The possibility of consumers or providers going away- Pending parts of a multipart crypto operation may need to be canceled before they are completed (an IPsec SA deleted for instance). A software provider may be unloaded, and a hardware provider can be DR'ed out (for dynamic reconfiguration).
• The ability to accommodate either contiguous or scatter-gather data.
• The need for efficiency.

The framework must enable the administrator to observe and control the behavior of the cryptographic services:

• Determine which crypto mechanisms are present.
• Display usage statistics.
• Change hardware and software providers with minimal disruption.
• Set a policy on the services and providers used by the system
• Mix and match operations from multipurpose providers.

 The system call interface has to provide access to the full capabilities offered by kernel providers to a user level library.
Kernel providers plug-in into the kernel SPI using an adaptation of the PKCS#11 standard interface, which is the interface currently supported by all the hardware cryptographic products vendors.

All the components will meet the Solaris requirements for security, robustness, and RAS.

2.2 Architecture

The framework has the following major components:

• A kernel level programming interface offering access to various cryptographic operation. Existing Solaris kernel components that use cryptographic operations are the consumers of this interface.
• A pluggable SPI (service provider interface) for Sun and third party cryptographic modules and device drivers.
• A pseudo device driver (/dev/crypto) offering an ioctl interface to the pkcs11_kernel.so delivered by the User Cryptographic Framework (UEF, PSARC case 2001/488), for accessing the cryptographic services offered by the hardware providers.
• A pseudo device driver (/dev/cryptoadm) for the administration of the framework.
• Scheduling/load balancing for cryptographic operations requests from kernel consumers, and from system calls to /dev/crypto.
• A command line administrative interface.
• A daemon resource management and module verification functions.

An example of the sequence of operation single-part encryption coming from a user-level application is provided in (examples)

2.3 Interfaces

2.3.1 Programming interface:

2.3.1.1 Consumer model

 A generic calling sequence will have three parts:

• Context creation and initialization
• Context use
• Finalizing, result collecting and context destruction.

The context creation and initialization may re-use a previously pre-computed template of a cryptographic context.
The second part can have also several steps (several updates using the the context for example).
The three parts can be combined in one single function call operation.

The consumer code is expected to be aware of kernel constraints.
Calls coming from non-blockable contexts are expected to provide call-back routines, and be ready for asynchronous scheduling of their request.

Consumer code that submits an asynchronous request is given back a handle for that request. The consumer code will use that handle to cancel the request if it needs to (driver closing, ...).
The main arguments passed to an asynchronous cryptographic function are expected to be persistent and valid until either (1) the operation is complete, and the call-back routine returns, or (2) the consumer cancels the request.

2.3.1.2 Detailed interface

 The programming interface is specified in details in the following document:
Kernel Cryptographic programming interface specification
and a sample code of invoking the interface is provided under md5_example.c

2.3.2 Provider interface

2.3.2.1 Provider Model

 Providers can be classified into two types: hardware and software providers. They are different in terms of capabilities offered, limitations, the way they operate internally, and the way they interact with their environment, which is the Solaris kernel.

• Software Provider Model

• Hardware Provider Model

2.3.2.2 Detailed interface

The programming interface is specified in details in the following document:
Crypto SPI

2.3.3 Administrative Interface

 A command line interface, cryptoadm(1m)Administrative Interfaceis provided to administer the kernel cryptographic services. The command uses ioctls to the /dev/cryptoadm pseudo driver  /dev/cryptoadm ioctl interface

2.3.4 Interface to user-level libraries

 A pseudo device driver, /dev/crypto, provides the user level access to the cryptographic services from hardware providers through the kernel SPI. A clone of /dev/crypto is returned in every new open of the /dev/crypto special file. Operational ioctls cover the full PKCSs#11 needs from pkcs11_kernel.so. The ioctl interface is specified in detail in the  /dev/crypto ioctl interface document. The pseudo driver approach is leveraged from the design of the Kernel Cryptographic Library produced by the Networking, Security and Cryptographic Products Group, and ships with the SCA 1000.

3. Detailed design

3.1 Configuration

 Cryptographic providers make thier services available to the kernel framework by calling a registration routine from their _init() routine (for software providers), and their xx_attach() entry point (for hardware providers) , as described in (http://sac.eng.sun.com/PSARC/2001/553/commit_2.materials/cspi) Kernel Cryptographic Provider Interface.
Hardware providers are expected to have their force-autoattach global property to be set, so that their attach routine gets invoked for all the possible instances at boot time, and triggers their registrations.
The capabilities of software providers, on the other hand, are described in a  private configuration file, /etc/crypto/kcf.conf. The content of kcf.conf is not exposed. Its entries can be altered only by cryptoadm(1m) and via the *kcfconf action scripts. At boot time, a user-level program loads the description of the which software provider is capable of which mechanism to the kernel. Later, when a cryptographic request for a particular mechanism is submitted for the first time, all the software providers capable of that mechanism are loaded on-demand (if not yet done), and have them register, and get verified if necessary (see more details in  kcfd  ), and start being used by the framework.

3.2 Provider tables and mechanism chains

 Starting from the mechanism, the code of the kernel programming interface routines  needs to efficiently retrieve the provider(s) capable of handling the operation, and directly dispatch the call to the most appropriate provider, or queue a request for later scheduling. The framework maintains mechanism tables indexed by the internal mechanism number. There is one such table per group of operations: digest, mac, ciphers, ...
Each entry in the mechanisms table points to a chain of descriptors of providers of the corresponding mechanism. Handling a request for an MD5 digest, in the example below, will only involve considering the providers that advertise whether being capable of that mechanism. Information kept in the description of the provider will determine it can handle the specific request (block sizes limitations, data types, ...). The framework also maintains information in the provider descriptor structure to help in choosing the provider most appropriate for handling the request.
Providers will be represented by one provider descriptor for each mechanism they advertise when they register. Several provider descriptor structures may be allocated for a single multipurpose provider. This is a small memory trade-off that favors the efficient scheduling. This separation of the mechanisms offered by a particular provider also allows to selectively disable any mechanism from that provider, should the system policy mandate that.

3.3 Scheduling/load balancing

 A cryptographic function can be called either from the ioctl handling code, or from a kernel-level consumer calling the k-api. The call may result in the creation of a corresponding request that is queued for later scheduling. The best provider to handle the call is chosen before queuing, based on the matching of capabilities required to perform the operation, and the load on the eligible providers.
The framework maintains a global queue of asynchronous requests that can be honored only by software providers. The framework also maintains one queue per registered hardware provider for the requests assigned to it.
One kernel thread is associated with the every hardware provider's queue. Its job is to keep that provider constantly "fed", so as to maximize the usage of that provider.
The Global software queue is serviced by a pool of variable number of kernel threads attached to LWPs, which are created by a user daemon that starts at boot time. This allows the system to keep the amount of CPU resources allocated to cryptographic operations in kernel under control. The servicing threads are created as the demand in working threads increases, so that we maximize the utilization of all the CPUs on an multi-processor system.
The scheduler's design is detailed in the scheduler's design document.
The resources management daemon is specified in the kcfd document.

3.4 Sessions and object management

 Session-oriented providers register a non null crypto_session_ops  with their crypto_ops operation vector. The framework maintains one session open with such providers for calls coming from kernel consumers.
PKCS#11 applications access the object manipulation capabilities (e.g. secure key storage) offered by hardware providers, by opening a session and authenticating to the provider. The session management, authentication, and object manipulation are described in the
Authentication and Object Management design document.

3.5 Memory management

 Some of the structures that Kernel cryptographic framework relies on need to be allocated and freed for each request received from a consumer and submitted to a Provider.
In order to reduce the overhead associated with the allocation and freeing of these structures, the framework introduces the following new kmem caches.
Default behavior for constructors and destructors is assumed unless explicitly described. See the  scheduler design document for a
detailed description of these structures.

/* Structure for synchronous requests */
struct kmem_cache *crypto_sync_req_cache;

/* Structure for asynchronous requests */
struct kmem_cache *crypto_async_req_cache;

/* Request node in Provider queue */
struct kmem_cache *crypto_reqnode_cache;

/* Contexts allocated by KEF */
struct kmem_cache *crypto_ctx_cache;

In addition, the Providers are required to zeroize any information that they derived from keying material and stored in a context.

3.6 Observability

3.6.1 Statistics

 The framework maintains counters for the number of the successful and the number of failed operations  of each mechanism submitted providers. kstats are used for these statistics.
When invoked by a non-privileged user, the reporting snapshot routine will report zero for the sensitive stats.

3.6.2 Performance measurments

 The main entry points for the cryptographic operation have macros wrapping TNF probes at the entry and exits of the routines. The probes accurately measure the time spent inside each routine.

3.7 Extensibility

 Mechanisms are identified by their name, and not by predefined numbers. This project predefines a set of names of the string constants that corresponds to the subset of the PKCS#11 mechanisms that are being provided. The consumer code is supposed to dynamically retreive  the name assigned to a mechanism by calling crypto_mech2id(<mechanism_name>).
Providers pass the names of the mechanisms to the framework when they register them. They also pass the number they internally assign to the those mechanisms, and expect the framework to use those number in later references to those mechanisms. This efficient extensible mechanism is detailed in crypto_mech_info(9S).

Appendix A: Glossary

 Asymetric Encryption

Authentication

Authenticator

Block cipher

Cipher

Ciphertext

 Cryptographic context

Cryptographic operation:

 Initialization Vector

 Mechanism

Message digest

MAC (Message Authentication Code)

PKCS#11

Plaintext

Provider

Session

Stream cipher

Symmetric encryption

Appendix B: Attached documents

 Design Documents:
       k-api
        cspi
        kcfd
        scheduler
        ioctl
        ioctl-admin
        auth_obj_mgmt
        cryptoadm
        examples

Contract templates:
        cspi_contract_template
        k-api_contract_template

Man pages:
        crypto_bufcall_9f
        crypto_bufcall_alloc_9f
        crypto_bufcall_free_9f
        crypto_call_req_9s
        crypto_cancel_req_9s
        crypto_cancel_ctx_9s
        crypto_cipher_ops_9s
        crypto_control_ops_9s
        crypto_create_ctx_template_9f
        crypto_ctx_9s
        crypto_ctx_ops_9s
        crypto_data_9s
        crypto_digest_9f
        crypto_digest_ops_9s
        crypto_dual_cipher_mac_ops_9s
        crypto_dual_data_9s
        crypto_dual_ops_9s
        crypto_encrypt_9f
        crypto_encrypt_mac_9f
        crypto_get_mech_list_9f
        crypto_key_9s
        crypto_key_ops_9s
        crypto_mac_9f
        crypto_mac_decrypt_9f
        crypto_mac_ops_9s
        crypto_mech_info_9s
        crypto_mech2id_9s
        crypto_mechanism_9s
        crypto_notify_events_9s
        crypto_object_attribute_9s
        crypto_object_ops_9s
        crypto_op_notification_9f
        crypto_ops_9s
        crypto_provider_dev_9s
        crypto_provider_info_9s
        crypto_provider_management_ops_9s
        crypto_provider_notification_9f
        crypto_random_number_ops_9s
        crypto_register_provider_9f
        crypto_session_ops_9s
        crypto_sign_ops_9s
        crypto_unbufcall_9f
        crypto_unregister_provider_9f
        crypto_verify_ops_9s
        cryptoadm_1m
        kcfd_1m
        modlcrypto_9s

• Other  documents  refer to this framework as the kernel Encryption Framework (KEF).  The term "cryptographic" is more accurate, as it covers other areas under this project  such as message digesting, message authentication codes, signatures, etc...   the 'C' in cryptography collided with the 'C' of  Certificate in the parent project ECF (PSARC 2001/550).

• • Some of the definitions were taken from the "Cryptography and Network Security" textbook by William Stallings (second edition).