Re: [PATCH 00/11] libcrypto: Provide more __cleanup functions for zeroizing data

[Eric Biggers]

Hi Thomas,

On Thu, Aug 13, 2026 at 03:49:38PM +0200, Thomas Huth wrote:
> Code that uses crypto-related structures (containing keys or context data)
> should zeroize their local structures on the stack after use to avoid
> leaking this sensitive material via the stack when the function returns.
> Using the __cleanup() marker is a very elegant way to assert that the
> data is zeroized without having to painfully verify that each early return
> in a function might miss it.
> 
> Thus this series introduces zeroization functions for many crypto-related
> structures that can be used with __cleanup(). The series focuses on the
> introduction of the functions - most call sights will be adjusted to use
> these new functions in separate patch series later (since each subsystem
> needs separate review from the corresponding maintainer). However, I
> already included the two "safexcel" patches, since they already got ack'ed
> by the maintainer Antoine, so I think they should be fine to go via the
> libcrypto tree.
> 
> Note there is one minor ugliness in patch 10: Since sha2.h is also used
> in the x86 purgatory code, and that code ships with its own implementation
> of string functions, we have to compile the purgatory.c file with
> -D__NO_FORTIFY now to be able to include <linux/string.h> in sha2.h.
> I hope that solution is OK (especially since the sha256.c file in the
> same folder gets that treatment already, too), if not - I'm certainly
> open for other suggestions here!
> 
> Thomas Huth (11):
>   lib/crypto: aes: Provide a wrapper function for zeroizing
>     crypto_aes_ctx
>   crypto: safexcel - Simplify the check for a valid AES key
>   crypto: safexcel - zeroize crypto_aes_ctx with
>     __cleanup(aes_zeroize_ctx)
>   lib/crypto: aes: Provide functions for zeroizing aes_key and
>     aes_enckey
>   lib/crypto: aes: Use aes_zeroize_*key() instead of memzero_explicit()
>   lib/crypto: md5: Provide a function for zeroizing hmac_md5_ctx
>     structures
>   lib/crypto: md5: Use hmac_md5_zeroize_ctx() instead of
>     memzero_explicit()
>   lib/crypto: sha1: Provide a wrapper for zeroizing hmac_sha1_ctx
>   lib/crypto: sha1: Use hmac_sha1_zeroize_ctx() instead of
>     memzero_explicit()
>   x86/purgatory: Compile purgatory.c with -D__NO_FORTIFY
>   lib/crypto: sha2: Provide wrappers for zeroizing SHA2 hmac_sha*_ctx
>     structures

I'm taking a look at these again for 7.3.  This is still missing quite a
few of the crypto library structs.  I would prefer to handle them all in
a consistent way.

Also, given that we'll end up with a lot of these, we should be
thoughtful about the kerneldoc.  Using aes_enckey as an example:

/**
 * aes_zeroize_enckey() - Zeroize an aes_enckey structure
 * @key: The location of the key structure that should be zeroized
 *
 * Explicitly fills the aes_enckey with zeroes. For example, use it with
 * __cleanup() for local aes_enckey structures on the stack, so that their
 * content is not leaked when the context is left.
 */

It's not clear what is meant by "context".  And it doesn't explicitly
connect the zeroization requirement to the lifetime of the struct, so I
don't think it makes it clear when this should be called.  It also says
nothing about kfree_sensitive() which many users should use instead.

Meanwhile, aes_prepareenckey() already has the following, which at least
connects the zeroization requirement to the lifetime of the key:

   * The caller is responsible for zeroizing both the struct aes_enckey and the    
   * raw key once they are no longer needed.

How about we remove that and the free-form description of
aes_zeroize_enckey(), and instead expand the comment on the struct
itself:

/**
 * struct aes_enckey - An AES key prepared for encryption
 * ...
 * Once prepared, users must zeroize this struct at the end of its lifetime.     
 * For stack-allocated structs, use __cleanup(aes_zeroize_enckey) to zeroize     
 * when the variable goes out of scope.  For slab-allocated structs, use         
 * kfree_sensitive() or else call aes_zeroize_enckey() before freeing.       
 */

That would connect the zeroization requirement to the actual struct and
its lifetime, and make it clear how to handle each case.  It would also
make it clear that stack allocation is supported for this struct, which
might not have been obvious before.

aes_zeroize_enckey() would then omit a free-form description, which
makes sense as it's a trivial wrapper around memzero_explicit():

/**
 * aes_zeroize_enckey() - Zeroize an aes_enckey structure
 * @key: The aes_enckey to zeroize
 */
static inline void aes_zeroize_enckey(struct aes_enckey *key)
{
	memzero_explicit(key, sizeof(*key));
}

Similarly for all the other structs, of course.

(For the hash contexts, the struct comment should mention that the
finalization function zeroizes as well.)

Does that sound good?

- Eric