Cryptographic API

Relevant source files

The following files were used as context for generating this wiki page:

• Documentation/crypto/index.rst
• Documentation/crypto/api-intro.rst
• Documentation/crypto/libcrypto.rst
• Documentation/crypto/krb5.rst
• Documentation/kernel-hacking/hacking.rst

The Linux kernel Cryptographic API provides a comprehensive framework for cryptographic operations, including encryption, hashing, and compression. It supports both high-level user interfaces for general kernel tasks and low-level registration for algorithm developers. The API primarily processes data using scatterlists (page vectors), which allows for efficient in-place encryption and avoids unnecessary memory linearization, especially for network protocols like IPsec.

Sources: Documentation/crypto/api-intro.rst:5-15, Documentation/crypto/index.rst:7-12

API Architecture and Layering

The API uses a layered design to separate user-facing interfaces from the underlying algorithm implementations. This structure allows new algorithms to register dynamically without changing the user-level logic.

Concept Layers

• Transform API: The user interface for interacting with cryptographic objects.
• Transform Ops: Per-type logic glue (e.g., cipher.c, compress.c) that handles specific cryptographic behavior.
• Algorithm API: The interface for registering new algorithms with the kernel.

Sources: Documentation/crypto/api-intro.rst:26-31

Data Flow Overview

The following diagram illustrates the interaction between a user, the transform object, and the underlying algorithm registration.

The Scatterlist Crypto API works directly on pages via scatterlists, enabling in-place processing for compatible modes like ECB.
Sources: Documentation/crypto/api-intro.rst:7-31

Core Transform Types

The API supports five primary transform types. While "Block Ciphers" is a common term, the API uses it to support both stream and block ciphers, distinguishing them by the amount of data they can process at once.

Transform Type	Description	Block Size Requirement
AEAD	Authenticated Encryption with Associated Data	Varies by algorithm
Block Cipher	Supports stream and block ciphers for arbitrary data amounts	Multiples of block size
Cipher	Operates on exactly one block of data	Fixed block size
Compressor	Handles data compression and decompression	N/A
Hash	Computes cryptographic digests (e.g., MD5, SHA256)	N/A

Sources: Documentation/crypto/api-intro.rst:33-43

Crypto Library (libcrypto)

The lib/crypto/ library provides a faster, simplified alternative to the traditional Cryptographic API for kernel-internal users. It uses standard function calls instead of scatterlists and algorithm registries, reducing overhead for short inputs.

Library Organization

• lib/crypto/*.c: Implementation of cryptographic algorithms.
• lib/crypto/$(SRCARCH)/: Architecture-specific optimizations (e.g., AES instructions).
• include/crypto/: Common headers for both the library and the traditional API.

Sources: Documentation/crypto/libcrypto.rst:6-10, Documentation/crypto/libcrypto.rst:31-41

Comparison of API vs. Library

The library focuses on CPU-based implementations and utilizes KUnit for testing.

Kerberos V Cryptography API

The Kerberos 5 API provides specific cryptographic routines for key derivation, encryption, and checksumming. It is primarily used by network filesystems and GSSAPI implementations.

Derived Keys

The API derives specific keys from a transport key (TK) based on usage values:

• Kc: Used for checksum mode.
• Ke and Ki: Used for encryption mode.

Sources: Documentation/crypto/krb5.rst:11-20, Documentation/crypto/krb5.rst:75-78

Buffers and Modes

Small data pieces like keys are passed using struct krb5_buffer. The API provides functions to calculate required buffer sizes for confounders and checksums.

Operational Guidelines

Strict rules govern the allocation and calling context of cryptographic methods to prevent system deadlocks.

• Allocation: You must only allocate transforms in user context.
• Execution: You may call cryptographic methods from softirq or user contexts.
• Setkey: You should only call setkey methods from user context.
• Memory: Standard memory allocation functions without GFP_ATOMIC may sleep and should be avoided in interrupt context.

Sources: Documentation/crypto/api-intro.rst:65-70, Documentation/kernel-hacking/hacking.rst:215-220

Conclusion

The Cryptographic API provides a robust and layered framework for securing Linux kernel operations. By supporting both a high-performance libcrypto library for simple tasks and a flexible scatterlist-based API for complex networking needs like IPsec and Kerberos, it ensures efficient data protection across various hardware architectures. Developers must adhere to strict context rules to maintain system stability while utilizing these cryptographic primitives.

Sources: Documentation/crypto/api-intro.rst:5-15, Documentation/crypto/libcrypto.rst:74-78