Something went wrong. Try again.
(I'm so sorry!) Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
5.5 kB · 150 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151.. SPDX-License-Identifier: GPL-2.0-or-later
Crypto Key Zeroization======================
This document describes the conventions for zeroizing crypto structures in thekernel.
Note: the kernel follows traditional cryptographic terminology by usingthe term "zeroizing" to mean erasing sensitive parameters to preventtheir disclosure if the system is later compromised. This distinguishesit from zeroing memory for other purposes such as initialization.
.. contents::
Overview--------
Cryptographic key material and intermediate state (such as HMAC contexts) mustbe zeroized after use to prevent sensitive data from lingering on the stack orheap, 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 thememory. Unlike plain memset(), memzero_explicit() is guaranteed notto be optimized away by the compiler, even when the memory being clearedappears to be dead.
The crypto library builds on memzero_explicit() by providing typedzeroization helpers for each key and context structure. These helpers servetwo 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 bezeroized 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. manualzeroization`_ below).
Zeroization helpers-------------------
Each crypto structure that callers may need to zeroize should have acorresponding 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 thatwraps ``memzero_explicit()``, for example::
static inline void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx) { memzero_explicit(ctx, sizeof(*ctx)); }
Using __cleanup for automatic zeroization-----------------------------------------
The preferred way to zeroize stack-allocated key and context structures iswith the __cleanup() attribute. This ensures zeroization happens on allexit paths, including error returns and early exits. For example::
static int my_aesxts_setkey(..., const u8 *key, unsigned int len) { struct crypto_aes_ctx aes __cleanup(aes_zeroize_ctx); ...
/* Only half of the key data is cipher key */ keylen = (len >> 1); ret = aes_expandkey(&aes, key, keylen); if (ret) return ret;
... do something with the cipher key ...
/* The other half is the tweak key */ ret = aes_expandkey(&aes, (u8 *)(key + keylen), keylen); if (ret) return ret; /* <-- Could leak cipher key without __cleanup */
... do something with the tweak key ...
/* No need for memzero_explicit() at the end thanks to the __cleanup */ return 0; }
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 isthat 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 zeroizetheir context before returning. When this is the case, the kernel-doc for thefunction 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 alwaysreached) do not need to add __cleanup() or explicit zeroization.However, __cleanup() is still recommended whenever there are error pathsthat bypass ``..._final()``, as it ensures zeroization on all paths.
For algorithms where ``..._final()`` does *not* zeroize the context (such asthe SHAKE XOFs, where ``shake_squeeze()`` can be called multiple times),callers must explicitly zeroize the context by calling the appropriate helperor 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 */