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

[Jonathan Corbet <corbet@lwn.net>]

Thomas Huth <thuth@redhat.com> writes:

> 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

One nit...

> diff --git a/Documentation/crypto/libcrypto-zeroization.rst b/Documentation/crypto/libcrypto-zeroization.rst
> new file mode 100644
> index 0000000000000..ba9b05320ad53
> --- /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.

Don't mark up function names, just say memzero_explicit().  The
automarkup code will then do the right thing, including cross-references
when the functions have kerneldoc documentation.

Thanks,

jon