Commit 5846551b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

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



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

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c71e2c73a787ec7814db09bec3c1359779785bfa.1592203650.git.mchehab+huawei@kernel.org


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 0efaaa86

Documentation/crypto/api-intro.txt→Documentation/crypto/api-intro.rst

+99 −87
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=============================

Scatterlist Cryptographic API

=============================



INTRODUCTION

Introduction

============



The Scatterlist Crypto API takes page vectors (scatterlists) as

arguments, and works directly on pages.  In some cases (e.g. ECB
@@ -13,7 +17,8 @@ so that processing can be applied to paged skb's without the need 
for linearization.





DETAILS

Details

=======



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

API.
@@ -23,7 +28,7 @@ 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:

Conceptually, the API layering looks like this::



  [transform api]  (user interface)

  [transform ops]  (per-type logic glue e.g. cipher.c, compress.c)
@@ -44,7 +49,7 @@ 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:

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



	#include <crypto/hash.h>

	#include <linux/err.h>
@@ -78,7 +83,8 @@ Here's an example of how to use the API: 
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

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.





ADDING NEW ALGORITHMS

Adding New Algorithms

=====================



When submitting a new algorithm for inclusion, a mandatory requirement

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.





BUGS

Bugs

====



Send bug reports to:

    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>





FURTHER INFORMATION

Further Information

===================



For further patches and various updates, including the current TODO

list, see:

http://gondor.apana.org.au/~herbert/crypto/





AUTHORS

Authors

=======



James Morris

David S. Miller

Herbert Xu

- James Morris

- David S. Miller

- Herbert Xu





CREDITS

Credits

=======



The following people provided invaluable feedback during the development

of the API:



  Alexey Kuznetzov

  Rusty Russell

  Herbert Valerio Riedel

  Jeff Garzik

  Michael Richardson

  Andrew Morton

  Ingo Oeser

  Christoph Hellwig

  - Alexey Kuznetzov

  - Rusty Russell

  - Herbert Valerio Riedel

  - Jeff Garzik

  - Michael Richardson

  - Andrew Morton

  - Ingo Oeser

  - Christoph Hellwig



Portions of this API were derived from the following projects:



  Kerneli Cryptoapi (http://www.kerneli.org/)

    Alexander Kjeldaas

    Herbert Valerio Riedel

    Kyle McMartin

    Jean-Luc Cooke

    David Bryson

    Clemens Fruhwirth

    Tobias Ringstrom

    Harald Welte

   - Alexander Kjeldaas

   - Herbert Valerio Riedel

   - Kyle McMartin

   - Jean-Luc Cooke

   - David Bryson

   - Clemens Fruhwirth

   - Tobias Ringstrom

   - Harald Welte



and;



  Nettle (http://www.lysator.liu.se/~nisse/nettle/)

    Niels Möller

   - Niels Möller



Original developers of the crypto algorithms:



  Dana L. How (DES)

  Andrew Tridgell and Steve French (MD4)

  Colin Plumb (MD5)

  Steve Reid (SHA1)

  Jean-Luc Cooke (SHA256, SHA384, SHA512)

  Kazunori Miyazawa / USAGI (HMAC)

  Matthew Skala (Twofish)

  Dag Arne Osvik (Serpent)

  Brian Gladman (AES)

  Kartikey Mahendra Bhatt (CAST6)

  Jon Oberheide (ARC4)

  Jouni Malinen (Michael MIC)

  NTT(Nippon Telegraph and Telephone Corporation) (Camellia)

  - Dana L. How (DES)

  - Andrew Tridgell and Steve French (MD4)

  - Colin Plumb (MD5)

  - Steve Reid (SHA1)

  - Jean-Luc Cooke (SHA256, SHA384, SHA512)

  - Kazunori Miyazawa / USAGI (HMAC)

  - Matthew Skala (Twofish)

  - Dag Arne Osvik (Serpent)

  - Brian Gladman (AES)

  - Kartikey Mahendra Bhatt (CAST6)

  - Jon Oberheide (ARC4)

  - Jouni Malinen (Michael MIC)

  - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)



SHA1 algorithm contributors:

  Jean-Francois Dive

  - Jean-Francois Dive



DES algorithm contributors:

  Raimar Falke

  Gisle Sælensminde

  Niels Möller

  - Raimar Falke

  - Gisle Sælensminde

  - Niels Möller



Blowfish algorithm contributors:

  Herbert Valerio Riedel

  Kyle McMartin

  - Herbert Valerio Riedel

  - Kyle McMartin



Twofish algorithm contributors:

  Werner Koch

  Marc Mutz

  - Werner Koch

  - Marc Mutz



SHA256/384/512 algorithm contributors:

  Andrew McDonald

  Kyle McMartin

  Herbert Valerio Riedel

  - Andrew McDonald

  - Kyle McMartin

  - Herbert Valerio Riedel



AES algorithm contributors:

  Alexander Kjeldaas

  Herbert Valerio Riedel

  Kyle McMartin

  Adam J. Richter

  Fruhwirth Clemens (i586)

  Linus Torvalds (i586)

  - Alexander Kjeldaas

  - Herbert Valerio Riedel

  - Kyle McMartin

  - Adam J. Richter

  - Fruhwirth Clemens (i586)

  - Linus Torvalds (i586)



CAST5 algorithm contributors:

  Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).

  - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).



TEA/XTEA algorithm contributors:

  Aaron Grothe

  Michael Ringe

  - Aaron Grothe

  - Michael Ringe



Khazad algorithm contributors:

  Aaron Grothe

  - Aaron Grothe



Whirlpool algorithm contributors:

  Aaron Grothe

  Jean-Luc Cooke

  - Aaron Grothe

  - Jean-Luc Cooke



Anubis algorithm contributors:

  Aaron Grothe

  - Aaron Grothe



Tiger algorithm contributors:

  Aaron Grothe

  - Aaron Grothe



VIA PadLock contributors:

  Michal Ludvig

  - Michal Ludvig



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>



Please send any credits updates or corrections to:

Herbert Xu <herbert@gondor.apana.org.au>

Documentation/crypto/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@ for cryptographic use cases, as well as programming examples. 
   :maxdepth: 2



   intro

   api-intro

   architecture

   asymmetric-keys

   devel-algos

CRA Git | Maintained and supported by SUSTech CRA and CCSE