VirtualBox

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

Last change on this file since 93483 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year

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