linux.git/Documentation/crypto, branch vsnprintf Linux kernel source tree crypto: doc - Fix akcipher title reference 2024-10-10T09:08:02+00:00 Lukas Wunner lukas@wunner.de 2024-10-08T09:12:01+00:00 5c20772738e1d1d7bec41664eb9d61497e53c10e Stephen reports a documentation build warning for "make htmldocs" introduced by recent commit 6b34562f0cfe ("crypto: akcipher - Drop sign/verify operations"). The commit renamed a paragraph title in a header file, but neglected to amend the title reference in the API documentation. Fix it. Fixes: 6b34562f0cfe ("crypto: akcipher - Drop sign/verify operations") Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> Closes: https://lore.kernel.org/all/20241008172926.0b995ea7@canb.auug.org.au/ Signed-off-by: Lukas Wunner <lukas@wunner.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au> 
Stephen reports a documentation build warning for "make htmldocs"
introduced by recent commit 6b34562f0cfe ("crypto: akcipher - Drop
sign/verify operations").

The commit renamed a paragraph title in a header file, but neglected to
amend the title reference in the API documentation.  Fix it.

Fixes: 6b34562f0cfe ("crypto: akcipher - Drop sign/verify operations")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/all/20241008172926.0b995ea7@canb.auug.org.au/
Signed-off-by: Lukas Wunner <lukas@wunner.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
crypto: ecdsa - Move X9.62 signature size calculation into template 2024-10-05T05:22:04+00:00 Lukas Wunner lukas@wunner.de 2024-09-10T14:30:27+00:00 a2471684dae23a676b4badea306140d24e6507f5 software_key_query() returns the maximum signature and digest size for a given key to user space. When it only supported RSA keys, calculating those sizes was trivial as they were always equivalent to the key size. However when ECDSA was added, the function grew somewhat complicated calculations which take the ASN.1 encoding and curve into account. This doesn't scale well and adjusting the calculations is easily forgotten when adding support for new encodings or curves. In fact, when NIST P521 support was recently added, the function was initially not amended: https://lore.kernel.org/all/b749d5ee-c3b8-4cbd-b252-7773e4536e07@linux.ibm.com/ Introduce a ->max_size() callback to struct sig_alg and take advantage of it to move the signature size calculations to ecdsa-x962.c. Introduce a ->digest_size() callback to struct sig_alg and move the maximum ECDSA digest size to ecdsa.c. It is common across ecdsa-x962.c and the upcoming ecdsa-p1363.c and thus inherited by both of them. For all other algorithms, continue using the key size as maximum signature and digest size. Signed-off-by: Lukas Wunner <lukas@wunner.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au> 
software_key_query() returns the maximum signature and digest size for a
given key to user space.  When it only supported RSA keys, calculating
those sizes was trivial as they were always equivalent to the key size.

However when ECDSA was added, the function grew somewhat complicated
calculations which take the ASN.1 encoding and curve into account.
This doesn't scale well and adjusting the calculations is easily
forgotten when adding support for new encodings or curves.  In fact,
when NIST P521 support was recently added, the function was initially
not amended:

https://lore.kernel.org/all/b749d5ee-c3b8-4cbd-b252-7773e4536e07@linux.ibm.com/

Introduce a ->max_size() callback to struct sig_alg and take advantage
of it to move the signature size calculations to ecdsa-x962.c.

Introduce a ->digest_size() callback to struct sig_alg and move the
maximum ECDSA digest size to ecdsa.c.  It is common across ecdsa-x962.c
and the upcoming ecdsa-p1363.c and thus inherited by both of them.

For all other algorithms, continue using the key size as maximum
signature and digest size.

Signed-off-by: Lukas Wunner <lukas@wunner.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
crypto: sig - Rename crypto_sig_maxsize() to crypto_sig_keysize() 2024-10-05T05:22:04+00:00 Lukas Wunner lukas@wunner.de 2024-09-10T14:30:26+00:00 221f00418e726237dbe38ba627ce08b22d3667f7 crypto_sig_maxsize() is a bit of a misnomer as it doesn't return the maximum signature size, but rather the key size. Rename it as well as all implementations of the ->max_size callback. A subsequent commit introduces a crypto_sig_maxsize() function which returns the actual maximum signature size. While at it, change the return type of crypto_sig_keysize() from int to unsigned int for consistency with crypto_akcipher_maxsize(). None of the callers checks for a negative return value and an error condition can always be indicated by returning zero. Signed-off-by: Lukas Wunner <lukas@wunner.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au> 
crypto_sig_maxsize() is a bit of a misnomer as it doesn't return the
maximum signature size, but rather the key size.

Rename it as well as all implementations of the ->max_size callback.
A subsequent commit introduces a crypto_sig_maxsize() function which
returns the actual maximum signature size.

While at it, change the return type of crypto_sig_keysize() from int to
unsigned int for consistency with crypto_akcipher_maxsize().  None of
the callers checks for a negative return value and an error condition
can always be indicated by returning zero.

Signed-off-by: Lukas Wunner <lukas@wunner.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
crypto: akcipher - Drop sign/verify operations 2024-10-05T05:22:04+00:00 Lukas Wunner lukas@wunner.de 2024-09-10T14:30:21+00:00 6b34562f0cfe81f1f207fc7c146c4ff4b31eb625 A sig_alg backend has just been introduced and all asymmetric sign/verify algorithms have been migrated to it. The sign/verify operations can thus be dropped from akcipher_alg. It is now purely for asymmetric encrypt/decrypt. Move struct crypto_akcipher_sync_data from internal.h to akcipher.c and unexport crypto_akcipher_sync_{prep,post}(): They're no longer used by sig.c but only locally in akcipher.c. In crypto_akcipher_sync_{prep,post}(), drop various NULL pointer checks for data->dst as they were only necessary for the verify operation. In the crypto_sig_*() API calls, remove the forks that were necessary while algorithms were converted from crypto_akcipher to crypto_sig one by one. In struct akcipher_testvec, remove the "params", "param_len" and "algo" elements as they were only needed for the ecrdsa verify operation. Remove corresponding dead code from test_akcipher_one() as well. Signed-off-by: Lukas Wunner <lukas@wunner.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au> 
A sig_alg backend has just been introduced and all asymmetric
sign/verify algorithms have been migrated to it.

The sign/verify operations can thus be dropped from akcipher_alg.
It is now purely for asymmetric encrypt/decrypt.

Move struct crypto_akcipher_sync_data from internal.h to akcipher.c and
unexport crypto_akcipher_sync_{prep,post}():  They're no longer used by
sig.c but only locally in akcipher.c.

In crypto_akcipher_sync_{prep,post}(), drop various NULL pointer checks
for data->dst as they were only necessary for the verify operation.

In the crypto_sig_*() API calls, remove the forks that were necessary
while algorithms were converted from crypto_akcipher to crypto_sig
one by one.

In struct akcipher_testvec, remove the "params", "param_len" and "algo"
elements as they were only needed for the ecrdsa verify operation.
Remove corresponding dead code from test_akcipher_one() as well.

Signed-off-by: Lukas Wunner <lukas@wunner.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
crypto: sig - Introduce sig_alg backend 2024-10-05T05:22:04+00:00 Lukas Wunner lukas@wunner.de 2024-09-10T14:30:12+00:00 65c4c93caaf1a9fca2855942e338530967162d25 Commit 6cb8815f41a9 ("crypto: sig - Add interface for sign/verify") began a transition of asymmetric sign/verify operations from crypto_akcipher to a new crypto_sig frontend. Internally, the crypto_sig frontend still uses akcipher_alg as backend, however: "The link between sig and akcipher is meant to be temporary. The plan is to create a new low-level API for sig and then migrate the signature code over to that from akcipher." https://lore.kernel.org/r/ZrG6w9wsb-iiLZIF@gondor.apana.org.au/ "having a separate alg for sig is definitely where we want to be since there is very little that the two types actually share." https://lore.kernel.org/r/ZrHlpz4qnre0zWJO@gondor.apana.org.au/ Take the next step of that migration and augment the crypto_sig frontend with a sig_alg backend to which all algorithms can be moved. During the migration, there will briefly be signature algorithms that are still based on crypto_akcipher, whilst others are already based on crypto_sig. Allow for that by building a fork into crypto_sig_*() API calls (i.e. crypto_sig_maxsize() and friends) such that one of the two backends is selected based on the transform's cra_type. Signed-off-by: Lukas Wunner <lukas@wunner.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au> 
Commit 6cb8815f41a9 ("crypto: sig - Add interface for sign/verify")
began a transition of asymmetric sign/verify operations from
crypto_akcipher to a new crypto_sig frontend.

Internally, the crypto_sig frontend still uses akcipher_alg as backend,
however:

   "The link between sig and akcipher is meant to be temporary.  The
    plan is to create a new low-level API for sig and then migrate
    the signature code over to that from akcipher."
    https://lore.kernel.org/r/ZrG6w9wsb-iiLZIF@gondor.apana.org.au/

   "having a separate alg for sig is definitely where we want to
    be since there is very little that the two types actually share."
    https://lore.kernel.org/r/ZrHlpz4qnre0zWJO@gondor.apana.org.au/

Take the next step of that migration and augment the crypto_sig frontend
with a sig_alg backend to which all algorithms can be moved.

During the migration, there will briefly be signature algorithms that
are still based on crypto_akcipher, whilst others are already based on
crypto_sig.  Allow for that by building a fork into crypto_sig_*() API
calls (i.e. crypto_sig_maxsize() and friends) such that one of the two
backends is selected based on the transform's cra_type.

Signed-off-by: Lukas Wunner <lukas@wunner.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
docs: crypto: async-tx-api: fix broken code example 2024-06-12T21:41:09+00:00 Ahmad Fatoum a.fatoum@pengutronix.de 2024-05-29T08:08:29+00:00 e8496ad6d804234933791daf3198c3a7fee522aa The code example fails to compile: 1) addr_conv is defined twice, once as a VLA, which have been phased out 2) submit is not a pointer, but is still dereferenced with -> 3) The first call to async_xor() lacked the trailing semicolon Fix these issues and while at it, fix some code style nitpicks as well: 1) make the functions static as users are unlikely to export them 2) include the relevant header 3) Shorten the example a bit by removing a redundant variable definition Fixes: 04ce9ab385dc ("async_xor: permit callers to pass in a 'dma/page scribble' region") Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de> Reviewed-by: Andre Noll <maan@tuebingen.mpg.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240529-async-dma-docs-v2-1-8faf87e72e6d@pengutronix.de 
The code example fails to compile:

  1) addr_conv is defined twice, once as a VLA, which have been phased out

  2) submit is not a pointer, but is still dereferenced with ->

  3) The first call to async_xor() lacked the trailing semicolon

Fix these issues and while at it, fix some code style nitpicks as well:

  1) make the functions static as users are unlikely to export them

  2) include the relevant header

  3) Shorten the example a bit by removing a redundant variable
     definition

Fixes: 04ce9ab385dc ("async_xor: permit callers to pass in a 'dma/page scribble' region")
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
Reviewed-by: Andre Noll <maan@tuebingen.mpg.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240529-async-dma-docs-v2-1-8faf87e72e6d@pengutronix.de
Merge tag 'docs-6.8' of git://git.lwn.net/linux 2024-01-12T03:46:52+00:00 Linus Torvalds torvalds@linux-foundation.org 2024-01-12T03:46:52+00:00 5b9b41617bf3e1282cc60f07d3d52e62399aa4ba Pull documentation update from Jonathan Corbet: "Another moderately busy cycle for documentation, including: - The minimum Sphinx requirement has been raised to 2.4.4, following a warning that was added in 6.2 - Some reworking of the Documentation/process front page to, hopefully, make it more useful - Various kernel-doc tweaks to, for example, make it deal properly with __counted_by annotations - We have also restored a warning for documentation of nonexistent structure members that disappeared a while back. That had the delightful consequence of adding some 600 warnings to the docs build. A sustained effort by Randy, Vegard, and myself has addressed almost all of those, bringing the documentation back into sync with the code. The fixes are going through the appropriate maintainer trees - Various improvements to the HTML rendered docs, including automatic links to Git revisions and a nice new pulldown to make translations easy to access - Speaking of translations, more of those for Spanish and Chinese ... plus the usual stream of documentation updates and typo fixes" * tag 'docs-6.8' of git://git.lwn.net/linux: (57 commits) MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL A reworked process/index.rst ring-buffer/Documentation: Add documentation on buffer_percent file Translated the RISC-V architecture boot documentation. Docs: remove mentions of fdformat from util-linux Docs/zh_CN: Fix the meaning of DEBUG to pr_debug() Documentation: move driver-api/dcdbas to userspace-api/ Documentation: move driver-api/isapnp to userspace-api/ Documentation/core-api : fix typo in workqueue Documentation/trace: Fixed typos in the ftrace FLAGS section kernel-doc: handle a void function without producing a warning scripts/get_abi.pl: ignore some temp files docs: kernel_abi.py: fix command injection scripts/get_abi: fix source path leak CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer docs: translations: add translations links when they exist kernel-doc: Align quick help and the code MAINTAINERS: add reviewer for Spanish translations docs: ignore __counted_by attribute in structure definitions scripts: kernel-doc: Clarify missing struct member description .. 
Pull documentation update from Jonathan Corbet:
 "Another moderately busy cycle for documentation, including:

   - The minimum Sphinx requirement has been raised to 2.4.4, following
     a warning that was added in 6.2

   - Some reworking of the Documentation/process front page to,
     hopefully, make it more useful

   - Various kernel-doc tweaks to, for example, make it deal properly
     with __counted_by annotations

   - We have also restored a warning for documentation of nonexistent
     structure members that disappeared a while back. That had the
     delightful consequence of adding some 600 warnings to the docs
     build. A sustained effort by Randy, Vegard, and myself has
     addressed almost all of those, bringing the documentation back into
     sync with the code. The fixes are going through the appropriate
     maintainer trees

   - Various improvements to the HTML rendered docs, including automatic
     links to Git revisions and a nice new pulldown to make translations
     easy to access

   - Speaking of translations, more of those for Spanish and Chinese

  ... plus the usual stream of documentation updates and typo fixes"

* tag 'docs-6.8' of git://git.lwn.net/linux: (57 commits)
  MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL
  A reworked process/index.rst
  ring-buffer/Documentation: Add documentation on buffer_percent file
  Translated the RISC-V architecture boot documentation.
  Docs: remove mentions of fdformat from util-linux
  Docs/zh_CN: Fix the meaning of DEBUG to pr_debug()
  Documentation: move driver-api/dcdbas to userspace-api/
  Documentation: move driver-api/isapnp to userspace-api/
  Documentation/core-api : fix typo in workqueue
  Documentation/trace: Fixed typos in the ftrace FLAGS section
  kernel-doc: handle a void function without producing a warning
  scripts/get_abi.pl: ignore some temp files
  docs: kernel_abi.py: fix command injection
  scripts/get_abi: fix source path leak
  CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer
  docs: translations: add translations links when they exist
  kernel-doc: Align quick help and the code
  MAINTAINERS: add reviewer for Spanish translations
  docs: ignore __counted_by attribute in structure definitions
  scripts: kernel-doc: Clarify missing struct member description
  ..
crypto: octeontx2 - add devlink option to set t106 mode 2023-12-29T03:25:38+00:00 Srujana Challa schalla@marvell.com 2023-12-13T07:30:49+00:00 82f89f1aa6ca33a6c1e50ddb165e2d5b882025e1 On CN10KA B0/CN10KB, CPT scatter gather format has modified to support multi-seg in inline IPsec. Due to this CPT requires new firmware and doesn't work with CN10KA0/A1 firmware. To make HW works in backward compatibility mode or works with CN10KA0/A1 firmware, a bit(T106_MODE) is introduced in HW CSR. This patch adds devlink parameter for configuring T106_MODE. This patch also documents the devlink parameter under Documentation/crypto/device_drivers. Signed-off-by: Srujana Challa <schalla@marvell.com> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au> 
On CN10KA B0/CN10KB, CPT scatter gather format has modified
to support multi-seg in inline IPsec. Due to this CPT requires
new firmware and doesn't work with CN10KA0/A1 firmware. To make
HW works in backward compatibility mode or works with CN10KA0/A1
firmware, a bit(T106_MODE) is introduced in HW CSR.

This patch adds devlink parameter for configuring T106_MODE.
This patch also documents the devlink parameter under
Documentation/crypto/device_drivers.

Signed-off-by: Srujana Challa <schalla@marvell.com>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
Merge branch 'vegard' into docs-mw 2023-11-17T20:07:51+00:00 Jonathan Corbet corbet@lwn.net 2023-11-17T20:07:51+00:00 d591aefc6635694293a3088b3c7401504190bbec Vegard Nossum writes: This patch series replaces some instances of 'class:: toc-title' with toctree's :caption: attribute, see the last patch in the series for some more rationale/explanation. 
Vegard Nossum writes:

  This patch series replaces some instances of 'class:: toc-title' with
  toctree's :caption: attribute, see the last patch in the series for some
  more rationale/explanation.
crypto: doc: properly format ToC headings 2023-11-17T20:05:26+00:00 Vegard Nossum vegard.nossum@oracle.com 2023-10-27T08:18:23+00:00 1f821382818a0dab85dbfff698b0fa0fff18cb36 "class:: toc-title" was a workaround for older Sphinx versions that are no longer supported. The canonical way to add a heading to the ToC is to use :caption:. Do that. Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Stephan Mueller <smueller@chronox.de> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231027081830.195056-5-vegard.nossum@oracle.com 
"class:: toc-title" was a workaround for older Sphinx versions that are
no longer supported.

The canonical way to add a heading to the ToC is to use :caption:.
Do that.

Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231027081830.195056-5-vegard.nossum@oracle.com