Re: [PATCH v3 13/13] lib/crypto: Add documentation about zeroization of key and context data

[Eric Biggers <ebiggers@kernel.org>]

On Thu, Sep 10, 2026 at 02:41:32PM +0200, Thomas Huth wrote:
> Add a central document about zeroization in libcrypto so we don't
> have to repeat this information in the individual kernel docs of
> the zeroization functions all over the place.
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  .../crypto/libcrypto-zeroization.rst          | 129 ++++++++++++++++++
>  Documentation/crypto/libcrypto.rst            |   1 +
>  2 files changed, 130 insertions(+)
>  create mode 100644 Documentation/crypto/libcrypto-zeroization.rst
> 
> diff --git a/Documentation/crypto/libcrypto-zeroization.rst b/Documentation/crypto/libcrypto-zeroization.rst
> new file mode 100644
> index 0000000000000..2a12417e335a3
> --- /dev/null
> +++ b/Documentation/crypto/libcrypto-zeroization.rst
> @@ -0,0 +1,129 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +Crypto Key Zeroization
> +======================
> +
> +This document describes the conventions for zeroizing crypto structures in the
> +kernel.

There should be a note about why it's being called "zeroizing" and not
just "zeroing".  Something like:

    Note: the kernel follows traditional cryptographic terminology by using
    the term "zeroizing" to mean erasing sensitive parameters to prevent
    their disclosure if the system is later compromised.  This distinguishes
    it from zeroing memory for other purposes such as initialization.

> +These helpers should include kernel-doc comments following the standard
> +conventions::
> +
> +    /**
> +     * hmac_sha256_zeroize_ctx() - Zeroize an hmac_sha256_ctx structure
> +     * @ctx: The hmac_sha256_ctx context to zeroize
> +     */

We might as well have these kerneldoc comments, but I don't it's helpful
to repeat them here in this Documentation/ file like this.  It's just
another thing that could get out of sync.

> +Using __cleanup for automatic zeroization
> +-----------------------------------------
> +
> +The preferred way to zeroize stack-allocated key and context structures is
> +with the __cleanup() attribute.  This ensures zeroization happens on all
> +exit paths, including error returns and early exits.

Could use a (minimal) code example.

- Eric