VirtualBox

source: vbox/trunk/include/iprt/memsafer.h@ 103224

Last change on this file since 103224 was 99739, checked in by vboxsync, 17 months ago

*: doxygen corrections (mostly about removing @returns from functions returning void).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.0 KB
Line 
1/** @file
2 * IPRT - Memory Allocate for Sensitive Data.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_memsafer_h
37#define IPRT_INCLUDED_memsafer_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/mem.h> /* RTMEM_TAG */
43
44RT_C_DECLS_BEGIN
45
46
47/** @defgroup grp_rt_memsafer RTMemSafer - Memory Allocator for Sensitive Data
48 * @ingroup grp_rt
49 *
50 * This API doesn't provide 100% secure storage, it only provider more secure
51 * and safer storage. Thus the API isn't called RTMemSafe because you cannot
52 * assume the data is safe against all kinds of extraction methods.
53 *
54 * The API guarantee that the memory won't be returned to the system containing
55 * any of the information you put there. It will be repeatedly wiped after use.
56 *
57 * The API tries to isolate your data from other information stored in the
58 * process/system. How well this is done depends on the implementation. The
59 * more complicated implementations will provide protection against heartbleed
60 * like bugs where pieces of the heap is copied onto the wire.
61 *
62 * The more hardened implementations of the API will also do their best to
63 * prevent the memory from ending up in process dumps or being readable by
64 * debuggers.
65 *
66 * Finally, two functions are provided for scrambling the sensitive memory while
67 * it's not in use.
68 *
69 * @{
70 */
71
72/** @name RTMEMSAFER_F_XXX
73 * @{ */
74/** Require the memory to not hit the page file.
75 * @remarks Makes not guarantees with regards to hibernation /
76 * suspend-to-disk. */
77#define RTMEMSAFER_F_REQUIRE_NOT_PAGABLE RT_BIT_32(0)
78/** Mask of valid bits. */
79#define RTMEMSAFER_F_VALID_MASK UINT32_C(0x00000001)
80/** @} */
81
82/**
83 * Scrambles memory allocated by RTMemSaferAllocZEx and associates after use.
84 *
85 * Call this when the sensitive data isn't actively being used. It will at a
86 * minimum make sure the data is slightly scrambled, how hard it is to unbutton
87 * is dependent on which implementation is used and available host support.
88 *
89 * The user must synchronize calls to RTMemSaferScramble and
90 * RTMemSaferUnscramble, this memory allocator provides no help and keeps no
91 * state information around.
92 *
93 * @returns IPRT status code.
94 * @param pv The pointer returned by the allocation function.
95 * @param cb The exact size given to the allocation function.
96 */
97RTDECL(int) RTMemSaferScramble(void *pv, size_t cb);
98
99/**
100 * Unscrambles memory allocated by RTMemSaferAllocZEx and associates before use.
101 *
102 * This undoes the effect of RTMemSaferScramble.
103 *
104 * @returns IPRT status code.
105 * @param pv The pointer returned by the allocation function.
106 * @param cb The exact size given to the allocation function.
107 */
108RTDECL(int) RTMemSaferUnscramble(void *pv, size_t cb);
109
110/**
111 * Allocates memory for sensitive data.
112 *
113 * Some effort will be taken to isolate the data from other memory allocation.
114 * Memory is always zeroed.
115 *
116 * @returns IPRT status code.
117 * @param ppvNew Where to return the pointer to the memory.
118 * @param cb Number of bytes to allocate.
119 * @param fFlags Flags for controlling the allocation, see
120 * RTMEMSAFER_F_XXX.
121 * @param pszTag Allocation tag used for statistics and such.
122 */
123RTDECL(int) RTMemSaferAllocZExTag(void **ppvNew, size_t cb, uint32_t fFlags, const char *pszTag) RT_NO_THROW_PROTO;
124
125/**
126 * Allocates memory for sensitive data.
127 *
128 * Some effort will be taken to isolate the data from other memory allocation.
129 * Memory is always zeroed.
130 *
131 * @returns IPRT status code.
132 * @param a_ppvNew Where to return the pointer to the memory.
133 * @param a_cb Number of bytes to allocate.
134 * @param a_fFlags Flags for controlling the allocation, see
135 * RTMEMSAFER_F_XXX.
136 */
137#define RTMemSaferAllocZEx(a_ppvNew, a_cb, a_fFlags) RTMemSaferAllocZExTag(a_ppvNew, a_cb, a_fFlags, RTMEM_TAG)
138
139/**
140 * Allocates memory for sensitive data.
141 *
142 * Some effort will be taken to isolate the data from other memory allocation.
143 * Memory is always zeroed.
144 *
145 * @returns Pointer to the allocated memory.
146 * @param cb Number of bytes to allocate.
147 * @param pszTag Allocation tag used for statistics and such.
148 */
149RTDECL(void *) RTMemSaferAllocZTag(size_t cb, const char *pszTag) RT_NO_THROW_PROTO;
150
151/**
152 * Allocates memory for sensitive data.
153 *
154 * Some effort will be taken to isolate the data from other memory allocation.
155 * Memory is always zeroed.
156 *
157 * @returns Pointer to the allocated memory.
158 * @param a_cb Number of bytes to allocate.
159 */
160#define RTMemSaferAllocZ(a_cb) RTMemSaferAllocZTag(a_cb, RTMEM_TAG)
161
162
163/**
164 * Reallocates memory allocated by RTMemSaferAllocZEx, RTMemSaferAllocZ,
165 * RTMemSaferAllocZExTag, or RTMemSaferAllocZTag.
166 *
167 * When extending the allocation, the new memory will be zeroed. When shrinking
168 * the allocation the left over memory will be wiped clean using
169 * RTMemWipeThorougly.
170 *
171 * The function follows the standard realloc behavior.
172 *
173 * @returns IPRT status code.
174 * @param cbOld The current allocation size.
175 * @param pvOld The current allocation.
176 * @param cbNew The size of the new allocation.
177 * @param ppvNew Where to return the pointer to the new memory.
178 * @param fFlags Flags for controlling the allocation, see
179 * RTMEMSAFER_F_XXX. It is not permitted to drop saftely
180 * requirments after the initial allocation.
181 * @param pszTag Allocation tag used for statistics and such.
182 */
183RTDECL(int) RTMemSaferReallocZExTag(size_t cbOld, void *pvOld, size_t cbNew, void **ppvNew, uint32_t fFlags, const char *pszTag) RT_NO_THROW_PROTO;
184
185/**
186 * Reallocates memory allocated by RTMemSaferAllocZEx, RTMemSaferAllocZ,
187 * RTMemSaferAllocZExTag, or RTMemSaferAllocZTag.
188 *
189 * When extending the allocation, the new memory will be zeroed. When shrinking
190 * the allocation the left over memory will be wiped clean using
191 * RTMemWipeThorougly.
192 *
193 * The function follows the standard realloc behavior.
194 *
195 * @returns IPRT status code.
196 * @param a_cbOld The current allocation size.
197 * @param a_pvOld The current allocation.
198 * @param a_cbNew The size of the new allocation.
199 * @param a_ppvNew Where to return the pointer to the new memory.
200 * @param a_fFlags Flags for controlling the allocation. See RTMEMSAFER_ALLOC_EX_FLAGS_* defines,
201 * this takes only effect when allocating completely new memory, for extending or
202 * shrinking existing allocations the flags of the allocation take precedence.
203 */
204#define RTMemSaferReallocZEx(a_cbOld, a_pvOld, a_cbNew, a_ppvNew, a_fFlags) \
205 RTMemSaferReallocZExTag(a_cbOld, a_pvOld, a_cbNew, a_ppvNew, a_fFlags, RTMEM_TAG)
206
207/**
208 * Reallocates memory allocated by RTMemSaferAllocZ or RTMemSaferAllocZTag.
209 *
210 * When extending the allocation, the new memory will be zeroed. When shrinking
211 * the allocation the left over memory will be wiped clean using
212 * RTMemWipeThorougly.
213 *
214 * The function follows the standard realloc behavior.
215 *
216 * @returns Pointer to the allocated memory.
217 * @param cbOld The current allocation size.
218 * @param pvOld The current allocation.
219 * @param cbNew The size of the new allocation.
220 * @param pszTag Allocation tag used for statistics and such.
221 */
222RTDECL(void *) RTMemSaferReallocZTag(size_t cbOld, void *pvOld, size_t cbNew, const char *pszTag) RT_NO_THROW_PROTO;
223
224/**
225 * Reallocates memory allocated by RTMemSaferAllocZ or RTMemSaferAllocZTag.
226 *
227 * When extending the allocation, the new memory will be zeroed. When shrinking
228 * the allocation the left over memory will be wiped clean using
229 * RTMemWipeThorougly.
230 *
231 * The function follows the standard realloc behavior.
232 *
233 * @returns Pointer to the allocated memory.
234 * @param a_cbOld The current allocation size.
235 * @param a_pvOld The current allocation.
236 * @param a_cbNew The size of the new allocation.
237 */
238#define RTMemSaferReallocZ(a_cbOld, a_pvOld, a_cbNew) RTMemSaferReallocZTag(a_cbOld, a_pvOld, a_cbNew, RTMEM_TAG)
239
240
241/**
242 * Frees memory allocated by RTMemSaferAllocZ* or RTMemSaferReallocZ*.
243 *
244 * Before freeing the allocated memory, it will be wiped clean using
245 * RTMemWipeThorougly.
246 *
247 * @param pv The allocation.
248 * @param cb The allocation size.
249 */
250RTDECL(void) RTMemSaferFree(void *pv, size_t cb) RT_NO_THROW_PROTO;
251
252/**
253 * Gets the amount of memory allocated at @a pv.
254 *
255 * This can be used to check if the allocation was made using an RTMemSafer API.
256 *
257 * @returns Allocation size in bytes, 0 if not a RTMemSafer allocation.
258 * @param pv The alleged RTMemSafer allocation.
259 *
260 * @note Not supported in all contexts and implementations of the API.
261 */
262RTDECL(size_t) RTMemSaferGetSize(void *pv) RT_NO_THROW_PROTO;
263
264
265/** @} */
266RT_C_DECLS_END
267
268#endif /* !IPRT_INCLUDED_memsafer_h */
269
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette