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

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

[Thomas Huth]

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.
+
+.. contents::
+
+Overview
+--------
+
+Cryptographic key material and intermediate state (such as HMAC contexts) must
+be zeroized after use to prevent sensitive data from lingering on the stack or
+heap, where it could be leaked through memory disclosure vulnerabilities,
+crash dumps, or cold-boot attacks.
+
+For memory that has been allocated with kmalloc() or a similar function,
+kfree_sensitive() should be used instead of kfree() to release the memory.
+
+For other cases, the kernel provides memzero_explicit() for clearing the
+memory.  Unlike plain memset(), memzero_explicit() is guaranteed not
+to be optimized away by the compiler, even when the memory being cleared
+appears to be dead.
+
+The crypto library builds on memzero_explicit() by providing typed
+zeroization helpers for each key and context structure.  These helpers serve
+two purposes:
+
+1. They make __cleanup() annotations possible, so that structures on
+   the stack are automatically zeroized when they go out of scope.
+
+2. They improve readability by replacing ``memzero_explicit(&key, sizeof(key))``
+   with a self-documenting call like ``aes_zeroize_key(&key)``.
+
+
+What to zeroize
+---------------
+
+The following types of structures hold sensitive material and should be
+zeroized after use:
+
+- **Key structures** (e.g. ``struct aes_key``, ``struct hmac_sha256_key``):
+  contain expanded round keys or prepared key material.
+
+- **HMAC/MAC context structures** (e.g. ``struct hmac_sha256_ctx``,
+  ``struct aes_cmac_ctx``): contain inner and outer hash states derived from
+  the key.
+
+- **Hash context structures** (e.g. ``struct sha256_ctx``): may contain
+  sensitive data being hashed.
+
+Not all of these require explicit cleanup by callers.  Many ``..._final()``
+functions already zeroize their context internally (see `Automatic vs. manual
+zeroization`_ below).
+
+
+Zeroization helpers
+-------------------
+
+Each crypto structure that callers may need to zeroize should have a
+corresponding inline helper function.  The naming convention is::
+
+    <algorithm>_zeroize_<type>(struct <algorithm>_<type> *p);
+
+For example::
+
+    void aes_zeroize_key(struct aes_key *key);
+    void aes_zeroize_enckey(struct aes_enckey *key);
+    void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx);
+    void aes_cmac_zeroize_key(struct aes_cmac_key *key);
+    void aes_cmac_zeroize_ctx(struct aes_cmac_ctx *ctx);
+
+Each helper is a ``static inline`` function in the algorithm's header that
+wraps ``memzero_explicit()``, for example::
+
+    static inline void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx)
+    {
+            memzero_explicit(ctx, sizeof(*ctx));
+    }
+
+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
+     */
+
+
+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.
+
+Note that __cleanup() attributes should not be used in functions that use
+"goto" statements. The benefit of cleanup helpers is the removal of "gotos",
+and that "goto" statements can jump between scopes, so the expectation is
+that usage of "goto" and cleanup helpers is never mixed in the same function.
+
+
+Automatic vs. manual zeroization
+--------------------------------
+
+Many ``..._final()`` functions in the crypto library automatically zeroize
+their context before returning.  When this is the case, the kernel-doc for the
+function documents it::
+
+    After finishing, this zeroizes @ctx.  So the caller does not need to do it.
+
+In these cases, callers on simple code paths (where ``..._final()`` is always
+reached) do not need to add __cleanup() or explicit zeroization.
+However, __cleanup() is still recommended whenever there are error paths
+that bypass ``..._final()``, as it ensures zeroization on all paths.
+
+For algorithms where ``..._final()`` does *not* zeroize the context (such as
+the SHAKE XOFs, where ``shake_squeeze()`` can be called multiple times),
+callers must explicitly zeroize the context by calling the appropriate helper
+or using __cleanup(), for example::
+
+    struct shake_ctx ctx __cleanup(shake_zeroize_ctx);
+
+    shake256_init(&ctx);
+    shake_update(&ctx, data, data_len);
+    shake_squeeze(&ctx, out, out_len);
+    /* ctx is automatically zeroized at end of scope */
diff --git a/Documentation/crypto/libcrypto.rst b/Documentation/crypto/libcrypto.rst
index e911e05215979..9533c12caa79d 100644
--- a/Documentation/crypto/libcrypto.rst
+++ b/Documentation/crypto/libcrypto.rst
@@ -165,4 +165,5 @@ API documentation
    libcrypto-signature
    libcrypto-unauth-encryption
    libcrypto-utils
+   libcrypto-zeroization
    sha3
-- 
2.55.0

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

[Eric Biggers]

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