The Linux Kernel Cryptographic API

A new general framework offers much-needed crypto services to all parts of the kernel.
Page Vectors

Before discussing the API structure, let's briefly look at memory pages and page vectors. As mentioned previously, a page is the fundamental unit of memory managed by the kernel (on i386, pages are 4KB in size). Consider a buffer containing, say, 1,460 bytes of user-space data. It belongs to a specific page in the kernel, offset from the start of the page by some amount, and has a length of 1,460 bytes. This buffer can be represented as a page-based tuple:

{ page, offset, length }

An interface, such as the cryptographic API that works directly with pages, needs to deal with this tuple, or page vector. An existing kernel data structure called a scatterlist is employed, which contains a page vector and normally is used for scatter-gather DMA operations.

The cryptographic API uses scatterlists to operate on arrays of discontiguous page vectors. The primary purpose of scatter-gather in the kernel is to avoid unnecessary copying of data. It also seems to result in cleaner code. Many readers will be familiar with scatter-gather I/O in the form of the readv() and writev() system calls. The kernel cryptographic API uses the same general concept but operates on pages instead of plain memory buffers.

API Structure

The API deals with two primary objects:

  • Algorithm implementations—kernel modules that contain the underlying algorithm code.

  • Transforms—objects that instantiate algorithms, manage internal state and handle common implementation logic. Transforms are managed by crypto_alloc_tfm() and crypto_free_tfm(). A set of API wrappers are provided to simplify transform use and to allow the properties of a transform's underlying algorithm to be queried.

The following pseudo-code demonstrates a typical use of the transform interface, where some kernel code needs to encrypt data using the Blowfish cipher in electronic codebook (ECB) mode:

tfm = crypto_alloc_tfm("blowfish",
                       CRYPTO_TFM_MODE_ECB);
crypto_cipher_setkey(tfm, key, keylength);
crypto_cipher_encrypt(tfm, &scatterlist,
                      numlists);
crypto_free_tfm(tfm);

As shown in Figure 1, the API is layered so that core logic is hidden from cryptography users and algorithm implementors. This core logic includes generic transform management, scatterlist manipulation and abstraction of underlying algorithms. Further down, per-algorithm-type logic is handled, such as cipher processing modes and utilizing digests for generating message authentication codes.

Figure 1. Structure of the Kernel Cryptographic API

The algorithm management layer contains logic for locating, loading and reference counting algorithm implementations. The latter is required to prevent nasty things from happening if an attempt is made to unload an algorithm module that is still in use.

An algorithm runtime query interface is provided so that calling code can determine which algorithms are available on the system. This is primarily intended for use by key negotiation protocols, such as ISAKMP/IKE.

Finally, the algorithm registration interface allows modules to register one or more algorithms, specifying various properties such as the name of the algorithm, its block size and minimum and maximum key sizes. The list of currently registered algorithms and their properties may be viewed in /proc/crypto.

Conclusions

This is still a young API that is likely to evolve somewhat, especially if some of the future design goals listed here are implemented.

In terms of API users, IPSec works and performs well, especially for a first cut with no performance optimizations. Existing kernel components that need cryptography are expected to convert to the new API over time, and hopefully, cool new projects will be developed because of it.

Acknowledgements

Many thanks to David Miller and Nancy Chan for reviewing this article.

Resources

email: jmorris@intercode.com.au

James Morris is a software developer involved with the Netfilter, LSM, SELinux and Linux kernel cryptographic API projects. He works as an independent consultant in Sydney, Australia.

______________________

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState