Skip to contentSkip to conversation

Improve the crypto library documentation

PATCH In review Eric Biggers 2 participants 5 messages Apr 18

Subsystems (3)
lore
Share & tools
lore

Eric Biggers

author maintainer
#0 lore raw

v2 cover Improve the crypto library documentation

While the crypto library already has a lot of kernel-doc, it's not being included in the HTML or PDF documentation (except for the SHA-3 kernenl-doc which is already included). Update Documentation/crypto/ to include it, and also add a high-level overview of the library.

I'd like to take this series via the libcrypto tree for 7.1.

Changed in v2:
- Use simple string replacement instead of regex in kdoc_parser.py
- Minor editorial revisions

Eric Biggers (2):
docs: kdoc: Expand 'at_least' when creating parameter list lib/crypto: docs: Add rst documentation to Documentation/crypto/

 Documentation/crypto/index.rst                |   2 +-
 .../crypto/libcrypto-blockcipher.rst          |  19 ++
 Documentation/crypto/libcrypto-hash.rst       |  86 +++++++++
 Documentation/crypto/libcrypto-signature.rst  |  11 ++
 Documentation/crypto/libcrypto-utils.rst      |   6 +
 Documentation/crypto/libcrypto.rst            | 165 ++++++++++++++++++
 Documentation/crypto/sha3.rst                 |   2 +
 tools/lib/python/kdoc/kdoc_parser.py          |   5 +
 8 files changed, 295 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst
 create mode 100644 Documentation/crypto/libcrypto-hash.rst
 create mode 100644 Documentation/crypto/libcrypto-signature.rst
 create mode 100644 Documentation/crypto/libcrypto-utils.rst
 create mode 100644 Documentation/crypto/libcrypto.rst

base-commit: 8541d8f725c673db3bd741947f27974358b2e163

Signature · 1 line
2.53.0
author maintainer
#1 lore raw

PATCH v2 1/2 docs: kdoc: Expand 'at_least' when creating parameter list

sphinx doesn't know that the kernel headers do:

    #define at_least static

Do this replacement before declarations are passed to it.

This prevents errors like the following from appearing once the lib/crypto/ kernel-doc is wired up to the sphinx build:

linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected ']' in end of array operator. [error at 59]
void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE])

---
 tools/lib/python/kdoc/kdoc_parser.py | 5 +++++
 1 file changed, 5 insertions(+)
tools/lib/python/kdoc/kdoc_parser.py +5 -0
index 74af7ae47aa47..c3f966da533e0 100644
@@ -437,10 +437,15 @@ class KernelDoc:
 
         for arg in args.split(splitter):
             # Ignore argument attributes
             arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
 
+            # Replace '[at_least ' with '[static '.  This allows sphinx to parse
+            # array parameter declarations like 'char A[at_least 4]', where
+            # 'at_least' is #defined to 'static' by the kernel headers.
+            arg = arg.replace('[at_least ', '[static ')
+
             # Strip leading/trailing spaces
             arg = arg.strip()
             arg = KernRe(r'\s+').sub(' ', arg, count=1)
 
             if arg.startswith('#'):
Signature · 1 line
2.53.0
reviewer Acked-by Tested-by on v2 1/2
#2 lore raw

Re: [PATCH v2 1/2] docs: kdoc: Expand 'at_least' when creating parameter list

Quoted 9 lines · Eric Biggers

sphinx doesn't know that the kernel headers do:

    #define at_least static

Do this replacement before declarations are passed to it.

This prevents errors like the following from appearing once the lib/crypto/ kernel-doc is wired up to the sphinx build:

Quoted 8 lines

linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected ']' in end of array operator. [error at 59]
void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE])

Quoted 24 lines
---
 tools/lib/python/kdoc/kdoc_parser.py | 5 +++++
 1 file changed, 5 insertions(+)
tools/lib/python/kdoc/kdoc_parser.py +5 -0
index 74af7ae47aa47..c3f966da533e0 100644
@@ -437,10 +437,15 @@ class KernelDoc:
 
         for arg in args.split(splitter):
             # Ignore argument attributes
             arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
 
+            # Replace '[at_least ' with '[static '.  This allows sphinx to parse
+            # array parameter declarations like 'char A[at_least 4]', where
+            # 'at_least' is #defined to 'static' by the kernel headers.
+            arg = arg.replace('[at_least ', '[static ')
+
             # Strip leading/trailing spaces
             arg = arg.strip()
             arg = KernRe(r'\s+').sub(' ', arg, count=1)
 
             if arg.startswith('#'):
Signature · 1 line
~Randy
author maintainer
#3 lore raw

PATCH v2 2/2 lib/crypto: docs: Add rst documentation to Documentation/crypto/

In reply to Eric Biggers

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".

---
 Documentation/crypto/index.rst                |   2 +-
 .../crypto/libcrypto-blockcipher.rst          |  19 ++
 Documentation/crypto/libcrypto-hash.rst       |  86 +++++++++
 Documentation/crypto/libcrypto-signature.rst  |  11 ++
 Documentation/crypto/libcrypto-utils.rst      |   6 +
 Documentation/crypto/libcrypto.rst            | 165 ++++++++++++++++++
 Documentation/crypto/sha3.rst                 |   2 +
 7 files changed, 290 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst
 create mode 100644 Documentation/crypto/libcrypto-hash.rst
 create mode 100644 Documentation/crypto/libcrypto-signature.rst
 create mode 100644 Documentation/crypto/libcrypto-utils.rst
 create mode 100644 Documentation/crypto/libcrypto.rst
Documentation/crypto/index.rst +1 -1
index 4ee667c446f99..705f186d662ba 100644
@@ -11,10 +11,11 @@ for cryptographic use cases, as well as programming examples.
 
 .. toctree::
    :caption: Table of contents
    :maxdepth: 2
 
+   libcrypto
    intro
    api-intro
    architecture
 
    async-tx-api
@@ -25,6 +26,5 @@ for cryptographic use cases, as well as programming examples.
    api
    api-samples
    descore-readme
    device_drivers/index
    krb5
-   sha3
Documentation/crypto/libcrypto-blockcipher.rst new file +19 -0
new file mode 100644
index 0000000000000..dd5ce2f8b5151
@@ -0,0 +1,19 @@
+.. 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 new file +86 -0

86 lines not on this page · raw message

Documentation/crypto/libcrypto-signature.rst new file +11 -0
new file mode 100644
index 0000000000000..e80d59fa51b6a
@@ -0,0 +1,11 @@
+.. 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 new file +6 -0
new file mode 100644
index 0000000000000..9d833f47ed390
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Utility functions
+=================
+
+.. kernel-doc:: include/crypto/utils.h
Documentation/crypto/libcrypto.rst new file +165 -0

165 lines not on this page · raw message

Documentation/crypto/sha3.rst +2 -0
index 37640f295118b..250669c98f6ba 100644
@@ -1,7 +1,9 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. _sha3:
+
 ==========================
 SHA-3 Algorithm Collection
 ==========================
 
 .. contents::
Signature · 1 line
2.53.0
reviewer Tested-by Reviewed-by on v2 2/2
#4 lore raw

Re: [PATCH v2 2/2] lib/crypto: docs: Add rst documentation to Documentation/crypto/

Quoted 15 lines · Eric Biggers

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.)

Quoted 5 lines

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

Quoted 15 lines
---
 Documentation/crypto/index.rst                |   2 +-
 .../crypto/libcrypto-blockcipher.rst          |  19 ++
 Documentation/crypto/libcrypto-hash.rst       |  86 +++++++++
 Documentation/crypto/libcrypto-signature.rst  |  11 ++
 Documentation/crypto/libcrypto-utils.rst      |   6 +
 Documentation/crypto/libcrypto.rst            | 165 ++++++++++++++++++
 Documentation/crypto/sha3.rst                 |   2 +
 7 files changed, 290 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst
 create mode 100644 Documentation/crypto/libcrypto-hash.rst
 create mode 100644 Documentation/crypto/libcrypto-signature.rst
 create mode 100644 Documentation/crypto/libcrypto-utils.rst
 create mode 100644 Documentation/crypto/libcrypto.rst
Signature · 1 line
~Randy