Documentation/crypto/api-intro.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/crypto/api-intro.rst
Extension
.rst
Size
6881 bytes
Lines
263
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

=============================
Scatterlist Cryptographic API
=============================

Introduction
============

The Scatterlist Crypto API takes page vectors (scatterlists) as
arguments, and works directly on pages.  In some cases (e.g. ECB
mode ciphers), this will allow for pages to be encrypted in-place
with no copying.

One of the initial goals of this design was to readily support IPsec,
so that processing can be applied to paged skb's without the need
for linearization.


Details
=======

At the lowest level are algorithms, which register dynamically with the
API.

'Transforms' are user-instantiated objects, which maintain state, handle all
of the implementation logic (e.g. manipulating page vectors) and provide an
abstraction to the underlying algorithms.  However, at the user
level they are very simple.

Conceptually, the API layering looks like this::

  [transform api]  (user interface)
  [transform ops]  (per-type logic glue e.g. cipher.c, compress.c)
  [algorithm api]  (for registering algorithms)

The idea is to make the user interface and algorithm registration API
very simple, while hiding the core logic from both.  Many good ideas
from existing APIs such as Cryptoapi and Nettle have been adapted for this.

The API currently supports five main types of transforms: AEAD (Authenticated
Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
Hashes.

Please note that Block Ciphers is somewhat of a misnomer.  It is in fact
meant to support all ciphers including stream ciphers.  The difference
between Block Ciphers and Ciphers is that the latter operates on exactly
one block while the former can operate on an arbitrary amount of data,
subject to block size requirements (i.e., non-stream ciphers can only
process multiples of blocks).

Here's an example of how to use the API::

	#include <crypto/hash.h>
	#include <linux/err.h>
	#include <linux/scatterlist.h>

	struct scatterlist sg[2];
	char result[128];
	struct crypto_ahash *tfm;
	struct ahash_request *req;

	tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
	if (IS_ERR(tfm))
		fail();

	/* ... set up the scatterlists ... */

	req = ahash_request_alloc(tfm, GFP_ATOMIC);
	if (!req)

Annotation

Implementation Notes