Commit e9af4f47 authored by Eric Biggers's avatar Eric Biggers
Browse files

lib/crypto: docs: Add rst documentation to Documentation/crypto/ 



Add a documentation file Documentation/crypto/libcrypto.rst which
provides a high-level overview of lib/crypto/.

Also add several sub-pages which include the kernel-doc for the
algorithms that have it.  This makes the existing, quite extensive
kernel-doc start being included in the HTML and PDF documentation.

Note that the intent is very much *not* that everyone has to read these
Documentation/ files.  The library is intended to be straightforward and
use familiar conventions; generally it should be possible to dive right
into the kernel-doc.  You shouldn't need to read a lot of documentation
to just call `sha256()`, for example, or to run the unit tests if you're
already familiar with KUnit.  (This differs from the traditional crypto
API which has a larger barrier to entry.)

Nevertheless, this seems worth adding.  Hopefully it is useful and makes
LWN no longer consider the library to be "meticulously undocumented".

Reviewed-by: default avatarArd Biesheuvel <ardb@kernel.org>
Tested-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Reviewed-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20260418192138.15556-3-ebiggers@kernel.org


Signed-off-by: default avatarEric Biggers <ebiggers@kernel.org>
parent 6fa6b5cb

Documentation/crypto/index.rst

+1 −1
Original line number Diff line number Diff line
@@ -13,6 +13,7 @@ for cryptographic use cases, as well as programming examples. 
   :caption: Table of contents

   :maxdepth: 2



   libcrypto

   intro

   api-intro

   architecture
@@ -27,4 +28,3 @@ for cryptographic use cases, as well as programming examples. 
   descore-readme

   device_drivers/index

   krb5
 
   sha3

Documentation/crypto/libcrypto-blockcipher.rst

0 → 100644
+19 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0-or-later



Block ciphers

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



AES

---



Support for the AES block cipher.



.. kernel-doc:: include/crypto/aes.h



DES

---



Support for the DES block cipher.  This algorithm is obsolete and is supported

only for backwards compatibility.



.. kernel-doc:: include/crypto/des.h

Documentation/crypto/libcrypto-hash.rst

0 → 100644
+86 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0-or-later



Hash functions, MACs, and XOFs

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



AES-CMAC and AES-XCBC-MAC

-------------------------



Support for the AES-CMAC and AES-XCBC-MAC message authentication codes.



.. kernel-doc:: include/crypto/aes-cbc-macs.h



BLAKE2b

-------



Support for the BLAKE2b cryptographic hash function.



.. kernel-doc:: include/crypto/blake2b.h



BLAKE2s

-------



Support for the BLAKE2s cryptographic hash function.



.. kernel-doc:: include/crypto/blake2s.h



GHASH and POLYVAL

-----------------



Support for the GHASH and POLYVAL universal hash functions.  These algorithms

are used only as internal components of other algorithms.



.. kernel-doc:: include/crypto/gf128hash.h



MD5

---



Support for the MD5 cryptographic hash function and HMAC-MD5.  This algorithm is

obsolete and is supported only for backwards compatibility.



.. kernel-doc:: include/crypto/md5.h



NH

--



Support for the NH universal hash function.  This algorithm is used only as an

internal component of other algorithms.



.. kernel-doc:: include/crypto/nh.h



Poly1305

--------



Support for the Poly1305 universal hash function.  This algorithm is used only

as an internal component of other algorithms.



.. kernel-doc:: include/crypto/poly1305.h



SHA-1

-----



Support for the SHA-1 cryptographic hash function and HMAC-SHA1.  This algorithm

is obsolete and is supported only for backwards compatibility.



.. kernel-doc:: include/crypto/sha1.h



SHA-2

-----



Support for the SHA-2 family of cryptographic hash functions, including SHA-224,

SHA-256, SHA-384, and SHA-512.  This also includes their corresponding HMACs:

HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512.



.. kernel-doc:: include/crypto/sha2.h



SHA-3

-----



The SHA-3 functions are documented in :ref:`sha3`.



SM3

---



Support for the SM3 cryptographic hash function.



.. kernel-doc:: include/crypto/sm3.h

Documentation/crypto/libcrypto-signature.rst

0 → 100644
+11 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0-or-later



Digital signature algorithms

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



ML-DSA

------



Support for the ML-DSA digital signature algorithm.



.. kernel-doc:: include/crypto/mldsa.h

Documentation/crypto/libcrypto-utils.rst

0 → 100644
+6 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0-or-later



Utility functions

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



.. kernel-doc:: include/crypto/utils.h