VirtualBox

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

Last change on this file since 69866 was 69105, checked in by vboxsync, 7 years ago

include/iprt/: (C) year

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