1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3Crypto Key Zeroization 4====================== 5 6This document describes the conventions for zeroizing crypto structures in the 7kernel. 8 9Note: the kernel follows traditional cryptographic terminology by using 10the term "zeroizing" to mean erasing sensitive parameters to prevent 11their disclosure if the system is later compromised. This distinguishes 12it from zeroing memory for other purposes such as initialization. 13 14.. contents:: 15 16Overview 17-------- 18 19Cryptographic key material and intermediate state (such as HMAC contexts) must 20be zeroized after use to prevent sensitive data from lingering on the stack or 21heap, where it could be leaked through memory disclosure vulnerabilities, 22crash dumps, or cold-boot attacks. 23 24For memory that has been allocated with kmalloc() or a similar function, 25kfree_sensitive() should be used instead of kfree() to release the memory. 26 27For other cases, the kernel provides memzero_explicit() for clearing the 28memory. Unlike plain memset(), memzero_explicit() is guaranteed not 29to be optimized away by the compiler, even when the memory being cleared 30appears to be dead. 31 32The crypto library builds on memzero_explicit() by providing typed 33zeroization helpers for each key and context structure. These helpers serve 34two purposes: 35 361. They make __cleanup() annotations possible, so that structures on 37 the stack are automatically zeroized when they go out of scope. 38 392. They improve readability by replacing ``memzero_explicit(&key, sizeof(key))`` 40 with a self-documenting call like ``aes_zeroize_key(&key)``. 41 42 43What to zeroize 44--------------- 45 46The following types of structures hold sensitive material and should be 47zeroized after use: 48 49- **Key structures** (e.g. ``struct aes_key``, ``struct hmac_sha256_key``): 50 contain expanded round keys or prepared key material. 51 52- **HMAC/MAC context structures** (e.g. ``struct hmac_sha256_ctx``, 53 ``struct aes_cmac_ctx``): contain inner and outer hash states derived from 54 the key. 55 56- **Hash context structures** (e.g. ``struct sha256_ctx``): may contain 57 sensitive data being hashed. 58 59Not all of these require explicit cleanup by callers. Many ``..._final()`` 60functions already zeroize their context internally (see `Automatic vs. manual 61zeroization`_ below). 62 63 64Zeroization helpers 65------------------- 66 67Each crypto structure that callers may need to zeroize should have a 68corresponding inline helper function. The naming convention is:: 69 70 <algorithm>_zeroize_<type>(struct <algorithm>_<type> *p); 71 72For example:: 73 74 void aes_zeroize_key(struct aes_key *key); 75 void aes_zeroize_enckey(struct aes_enckey *key); 76 void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx); 77 void aes_cmac_zeroize_key(struct aes_cmac_key *key); 78 void aes_cmac_zeroize_ctx(struct aes_cmac_ctx *ctx); 79 80Each helper is a ``static inline`` function in the algorithm's header that 81wraps ``memzero_explicit()``, for example:: 82 83 static inline void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx) 84 { 85 memzero_explicit(ctx, sizeof(*ctx)); 86 } 87 88 89Using __cleanup for automatic zeroization 90----------------------------------------- 91 92The preferred way to zeroize stack-allocated key and context structures is 93with the __cleanup() attribute. This ensures zeroization happens on all 94exit paths, including error returns and early exits. For example:: 95 96 static int my_aesxts_setkey(..., const u8 *key, unsigned int len) 97 { 98 struct crypto_aes_ctx aes __cleanup(aes_zeroize_ctx); 99 ... 100 101 /* Only half of the key data is cipher key */ 102 keylen = (len >> 1); 103 ret = aes_expandkey(&aes, key, keylen); 104 if (ret) 105 return ret; 106 107 ... do something with the cipher key ... 108 109 /* The other half is the tweak key */ 110 ret = aes_expandkey(&aes, (u8 *)(key + keylen), keylen); 111 if (ret) 112 return ret; /* <-- Could leak cipher key without __cleanup */ 113 114 ... do something with the tweak key ... 115 116 /* No need for memzero_explicit() at the end thanks to the __cleanup */ 117 return 0; 118 } 119 120Note that __cleanup() attributes should not be used in functions that use 121"goto" statements. The benefit of cleanup helpers is the removal of "gotos", 122and that "goto" statements can jump between scopes, so the expectation is 123that usage of "goto" and cleanup helpers is never mixed in the same function. 124 125 126Automatic vs. manual zeroization 127-------------------------------- 128 129Many ``..._final()`` functions in the crypto library automatically zeroize 130their context before returning. When this is the case, the kernel-doc for the 131function documents it:: 132 133 After finishing, this zeroizes @ctx. So the caller does not need to do it. 134 135In these cases, callers on simple code paths (where ``..._final()`` is always 136reached) do not need to add __cleanup() or explicit zeroization. 137However, __cleanup() is still recommended whenever there are error paths 138that bypass ``..._final()``, as it ensures zeroization on all paths. 139 140For algorithms where ``..._final()`` does *not* zeroize the context (such as 141the SHAKE XOFs, where ``shake_squeeze()`` can be called multiple times), 142callers must explicitly zeroize the context by calling the appropriate helper 143or using __cleanup(), for example:: 144 145 struct shake_ctx ctx __cleanup(shake_zeroize_ctx); 146 147 shake256_init(&ctx); 148 shake_update(&ctx, data, data_len); 149 shake_squeeze(&ctx, out, out_len); 150 /* ctx is automatically zeroized at end of scope */ 151