iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: crypto: convert api-intro.txt to ReST format

Browse Source 
- Change title markups;
- Mark literal blocks;
- Use list markups at authors/credits;
- Add blank lines when needed;
- Remove trailing whitespaces.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c71e2c73a787ec7814db09bec3c1359779785bfa.1592203650.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
2020-06-15 08:50:09 +02:00
committed by Jonathan Corbet
parent 0efaaa8658
commit 5846551bb1
2 changed files with 100 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
Documentation/crypto/api-intro.txt → Documentation/crypto/api-intro.rst
View File

@ -1,7 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Scatterlist Cryptographic API =============================
Scatterlist Cryptographic API
INTRODUCTION =============================
Introduction
============
The Scatterlist Crypto API takes page vectors (scatterlists) as The Scatterlist Crypto API takes page vectors (scatterlists) as
arguments, and works directly on pages. In some cases (e.g. ECB arguments, and works directly on pages. In some cases (e.g. ECB
@ -13,22 +17,23 @@ so that processing can be applied to paged skb's without the need
for linearization. for linearization.
DETAILS Details
=======
At the lowest level are algorithms, which register dynamically with the At the lowest level are algorithms, which register dynamically with the
API. API.
'Transforms' are user-instantiated objects, which maintain state, handle all 'Transforms' are user-instantiated objects, which maintain state, handle all
of the implementation logic (e.g. manipulating page vectors) and provide an of the implementation logic (e.g. manipulating page vectors) and provide an
abstraction to the underlying algorithms. However, at the user abstraction to the underlying algorithms. However, at the user
level they are very simple. level they are very simple.
Conceptually, the API layering looks like this: Conceptually, the API layering looks like this::
[transform api] (user interface) [transform api] (user interface)
[transform ops] (per-type logic glue e.g. cipher.c, compress.c) [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
[algorithm api] (for registering algorithms) [algorithm api] (for registering algorithms)
The idea is to make the user interface and algorithm registration API The idea is to make the user interface and algorithm registration API
very simple, while hiding the core logic from both. Many good ideas 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. from existing APIs such as Cryptoapi and Nettle have been adapted for this.
@ -44,21 +49,21 @@ 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 subject to block size requirements (i.e., non-stream ciphers can only
process multiples of blocks). process multiples of blocks).
Here's an example of how to use the API: Here's an example of how to use the API::
#include <crypto/hash.h> #include <crypto/hash.h>
#include <linux/err.h> #include <linux/err.h>
#include <linux/scatterlist.h> #include <linux/scatterlist.h>
struct scatterlist sg[2]; struct scatterlist sg[2];
char result[128]; char result[128];
struct crypto_ahash *tfm; struct crypto_ahash *tfm;
struct ahash_request *req; struct ahash_request *req;
tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC); tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
if (IS_ERR(tfm)) if (IS_ERR(tfm))
fail(); fail();
/* ... set up the scatterlists ... */ /* ... set up the scatterlists ... */
req = ahash_request_alloc(tfm, GFP_ATOMIC); req = ahash_request_alloc(tfm, GFP_ATOMIC);
@ -67,18 +72,19 @@ Here's an example of how to use the API:
ahash_request_set_callback(req, 0, NULL, NULL); ahash_request_set_callback(req, 0, NULL, NULL);
ahash_request_set_crypt(req, sg, result, 2); ahash_request_set_crypt(req, sg, result, 2);
if (crypto_ahash_digest(req)) if (crypto_ahash_digest(req))
fail(); fail();
ahash_request_free(req); ahash_request_free(req);
crypto_free_ahash(tfm); crypto_free_ahash(tfm);
Many real examples are available in the regression test module (tcrypt.c). Many real examples are available in the regression test module (tcrypt.c).
DEVELOPER NOTES Developer Notes
===============
Transforms may only be allocated in user context, and cryptographic Transforms may only be allocated in user context, and cryptographic
methods may only be called from softirq and user contexts. For methods may only be called from softirq and user contexts. For
@ -91,7 +97,8 @@ size (typically 8 bytes). This prevents having to do any copying
across non-aligned page fragment boundaries. across non-aligned page fragment boundaries.
ADDING NEW ALGORITHMS Adding New Algorithms
=====================
When submitting a new algorithm for inclusion, a mandatory requirement When submitting a new algorithm for inclusion, a mandatory requirement
is that at least a few test vectors from known sources (preferably is that at least a few test vectors from known sources (preferably
@ -119,132 +126,137 @@ Also check the TODO list at the web site listed below to see what people
might already be working on. might already be working on.
BUGS Bugs
====
Send bug reports to: Send bug reports to:
linux-crypto@vger.kernel.org linux-crypto@vger.kernel.org
Cc: Herbert Xu <herbert@gondor.apana.org.au>,
Cc:
Herbert Xu <herbert@gondor.apana.org.au>,
David S. Miller <davem@redhat.com> David S. Miller <davem@redhat.com>
FURTHER INFORMATION Further Information
===================
For further patches and various updates, including the current TODO For further patches and various updates, including the current TODO
list, see: list, see:
http://gondor.apana.org.au/~herbert/crypto/ http://gondor.apana.org.au/~herbert/crypto/
AUTHORS Authors
=======
James Morris - James Morris
David S. Miller - David S. Miller
Herbert Xu - Herbert Xu
CREDITS Credits
=======
The following people provided invaluable feedback during the development The following people provided invaluable feedback during the development
of the API: of the API:
Alexey Kuznetzov - Alexey Kuznetzov
Rusty Russell - Rusty Russell
Herbert Valerio Riedel - Herbert Valerio Riedel
Jeff Garzik - Jeff Garzik
Michael Richardson - Michael Richardson
Andrew Morton - Andrew Morton
Ingo Oeser - Ingo Oeser
Christoph Hellwig - Christoph Hellwig
Portions of this API were derived from the following projects: Portions of this API were derived from the following projects:
Kerneli Cryptoapi (http://www.kerneli.org/) Kerneli Cryptoapi (http://www.kerneli.org/)
Alexander Kjeldaas - Alexander Kjeldaas
Herbert Valerio Riedel - Herbert Valerio Riedel
Kyle McMartin - Kyle McMartin
Jean-Luc Cooke - Jean-Luc Cooke
David Bryson - David Bryson
Clemens Fruhwirth - Clemens Fruhwirth
Tobias Ringstrom - Tobias Ringstrom
Harald Welte - Harald Welte
and; and;
Nettle (http://www.lysator.liu.se/~nisse/nettle/) Nettle (http://www.lysator.liu.se/~nisse/nettle/)
Niels Möller - Niels Möller
Original developers of the crypto algorithms: Original developers of the crypto algorithms:
Dana L. How (DES) - Dana L. How (DES)
Andrew Tridgell and Steve French (MD4) - Andrew Tridgell and Steve French (MD4)
Colin Plumb (MD5) - Colin Plumb (MD5)
Steve Reid (SHA1) - Steve Reid (SHA1)
Jean-Luc Cooke (SHA256, SHA384, SHA512) - Jean-Luc Cooke (SHA256, SHA384, SHA512)
Kazunori Miyazawa / USAGI (HMAC) - Kazunori Miyazawa / USAGI (HMAC)
Matthew Skala (Twofish) - Matthew Skala (Twofish)
Dag Arne Osvik (Serpent) - Dag Arne Osvik (Serpent)
Brian Gladman (AES) - Brian Gladman (AES)
Kartikey Mahendra Bhatt (CAST6) - Kartikey Mahendra Bhatt (CAST6)
Jon Oberheide (ARC4) - Jon Oberheide (ARC4)
Jouni Malinen (Michael MIC) - Jouni Malinen (Michael MIC)
NTT(Nippon Telegraph and Telephone Corporation) (Camellia) - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
SHA1 algorithm contributors: SHA1 algorithm contributors:
Jean-Francois Dive - Jean-Francois Dive
DES algorithm contributors: DES algorithm contributors:
Raimar Falke - Raimar Falke
Gisle Sælensminde - Gisle Sælensminde
Niels Möller - Niels Möller
Blowfish algorithm contributors: Blowfish algorithm contributors:
Herbert Valerio Riedel - Herbert Valerio Riedel
Kyle McMartin - Kyle McMartin
Twofish algorithm contributors: Twofish algorithm contributors:
Werner Koch - Werner Koch
Marc Mutz - Marc Mutz
SHA256/384/512 algorithm contributors: SHA256/384/512 algorithm contributors:
Andrew McDonald - Andrew McDonald
Kyle McMartin - Kyle McMartin
Herbert Valerio Riedel - Herbert Valerio Riedel
AES algorithm contributors: AES algorithm contributors:
Alexander Kjeldaas - Alexander Kjeldaas
Herbert Valerio Riedel - Herbert Valerio Riedel
Kyle McMartin - Kyle McMartin
Adam J. Richter - Adam J. Richter
Fruhwirth Clemens (i586) - Fruhwirth Clemens (i586)
Linus Torvalds (i586) - Linus Torvalds (i586)
CAST5 algorithm contributors: CAST5 algorithm contributors:
Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
TEA/XTEA algorithm contributors: TEA/XTEA algorithm contributors:
Aaron Grothe - Aaron Grothe
Michael Ringe - Michael Ringe
Khazad algorithm contributors: Khazad algorithm contributors:
Aaron Grothe - Aaron Grothe
Whirlpool algorithm contributors: Whirlpool algorithm contributors:
Aaron Grothe - Aaron Grothe
Jean-Luc Cooke - Jean-Luc Cooke
Anubis algorithm contributors: Anubis algorithm contributors:
Aaron Grothe - Aaron Grothe
Tiger algorithm contributors: Tiger algorithm contributors:
Aaron Grothe - Aaron Grothe
VIA PadLock contributors: VIA PadLock contributors:
Michal Ludvig - Michal Ludvig
Camellia algorithm contributors: Camellia algorithm contributors:
NTT(Nippon Telegraph and Telephone Corporation) (Camellia) - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
Please send any credits updates or corrections to: Please send any credits updates or corrections to:
Herbert Xu <herbert@gondor.apana.org.au> Herbert Xu <herbert@gondor.apana.org.au>

1
Documentation/crypto/index.rst
View File

@ -17,6 +17,7 @@ for cryptographic use cases, as well as programming examples.
:maxdepth: 2 :maxdepth: 2
intro intro
api-intro
architecture architecture
asymmetric-keys asymmetric-keys
devel-algos devel-algos