projects/linux·blob master · refs

150 lines · 5.4 KiB

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 */