Documentation/crypto/libcrypto.rst

Source file repositories/reference/linux-study-clean/Documentation/crypto/libcrypto.rst

File Facts

System
Linux kernel
Corpus path
Documentation/crypto/libcrypto.rst
Extension
.rst
Size
7349 bytes
Lines
166
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0-or-later

==============
Crypto library
==============

``lib/crypto/`` provides faster and easier access to cryptographic algorithms
than the traditional crypto API.

Each cryptographic algorithm is supported via a set of dedicated functions.
"Crypto agility", where needed, is left to calling code.

The crypto library functions are intended to be boring and straightforward, and
to follow familiar conventions.  Their primary documentation is their (fairly
extensive) kernel-doc.  This page just provides some extra high-level context.

Note that the crypto library isn't entirely new.  ``lib/`` has contained some
crypto functions since 2005.  Rather, it's just an approach that's been expanded
over time as it's been found to work well.  It also largely just matches how the
kernel already does things elsewhere.

Scope and intended audience
===========================

The crypto library documentation is primarily meant for kernel developers who
need to use a particular cryptographic algorithm(s) in kernel code.  For
example, "I just need to compute a SHA-256 hash."  A secondary audience is
developers working on the crypto algorithm implementations themselves.

If you're looking for more general information about cryptography, like the
differences between the different crypto algorithms or how to select an
appropriate algorithm, you should refer to external sources which cover that
type of information much more comprehensively.  If you need help selecting
algorithms for a new kernel feature that doesn't already have its algorithms
predefined, please reach out to ``linux-crypto@vger.kernel.org`` for advice.

Code organization
=================

- ``lib/crypto/*.c``: the crypto algorithm implementations

- ``lib/crypto/$(SRCARCH)/``: architecture-specific code for crypto algorithms.
  It is here rather than somewhere in ``arch/`` partly because this allows
  generic and architecture-optimized code to be easily built into a single
  loadable module (when the algorithm is set to 'm' in the kconfig).

- ``lib/crypto/tests/``: KUnit tests for the crypto algorithms

- ``include/crypto/``: crypto headers, for both the crypto library and the
  traditional crypto API

Generally, there is one kernel module per algorithm.  Sometimes related
algorithms are grouped into one module.  There is intentionally no common
framework, though there are some utility functions that multiple algorithms use.

Each algorithm module is controlled by a tristate kconfig symbol
``CRYPTO_LIB_$(ALGORITHM)``.  As is the norm for library functions in the
kernel, these are hidden symbols which don't show up in the kconfig menu.
Instead, they are just selected by all the kconfig symbols that need them.

Many of the algorithms have multiple implementations: a generic implementation
and architecture-optimized implementation(s).  Each module initialization
function, or initcall in the built-in case, automatically enables the best
implementation based on the available CPU features.

Note that the crypto library doesn't use the ``crypto/``,
``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories.  These
directories are used by the traditional crypto API.  When possible, algorithms
in the traditional crypto API are implemented by calls into the library.

Annotation

Implementation Notes