memsafer.h revision 13493ab7596e827b8d0caab2c89e635dd65f78f9
3258N/A * IPRT - Memory Allocate for Sensitive Data. 0N/A * Copyright (C) 2006-2014 Oracle Corporation 0N/A * This file is part of VirtualBox Open Source Edition (OSE), as 0N/A * you can redistribute it and/or modify it under the terms of the GNU 0N/A * General Public License (GPL) as published by the Free Software 0N/A * Foundation, in version 2 as it comes in the "COPYING" file of the 0N/A * VirtualBox OSE distribution. VirtualBox OSE is distributed in the 0N/A * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. 0N/A * The contents of this file may alternatively be used under the terms 0N/A * of the Common Development and Distribution License Version 1.0 0N/A * (CDDL) only, as it comes in the "COPYING.CDDL" file of the 0N/A * VirtualBox OSE distribution, in which case the provisions of the 0N/A * CDDL are applicable instead of those of the GPL. 2362N/A * You may elect to license modified versions of this file under the 2362N/A * terms and conditions of either the GPL or the CDDL or both. 0N/A/** @defgroup grp_rt_memsafer RTMemSafer - Memory Allocator for Sensitive Data 0N/A * This API doesn't provide 100% secure storage, it only provider more secure 0N/A * and safer storage. Thus the API isn't called RTMemSafe because you cannot 3258N/A * assume the data is safe against all kinds of extraction methods. 0N/A * The API guarantee that the memory won't be returned to the system containing 0N/A * any of the information you put there. It will be repeatedly wiped after use. 0N/A * The API tries to isolate your data from other information stored in the 0N/A * more complicated implementations will provide protection against heartbleed 0N/A * like bugs where pieces of the heap is copied onto the wire. 0N/A * The more hardened implementations of the API will also do their best to 0N/A * prevent the memory from ending up in process dumps or being readable by 0N/A * Finally, two functions are provided for scrambling the sensitive memory while 0N/A * Scrambles memory allocated by RTMemSaferAllocZEx and associates after use. 0N/A * Call this when the sensitive data isn't actively being used. It will at a 0N/A * minimum make sure the data is slightly scrambled, how hard it is to unbutton 0N/A * is dependent on which implementation is used and available host support. 0N/A * The user must synchronize calls to RTMemSaferScramble and 0N/A * RTMemSaferUnscramble, this memory allocator provides no help and keeps no 0N/A * state information around. 0N/A * @returns IPRT status code. 0N/A * @param pv The pointer returned by the allocation function. 0N/A * @param cb The exact size given to the allocation function. 0N/A * Unscrambles memory allocated by RTMemSaferAllocZEx and associates before use. 0N/A * This undoes the effect of RTMemSaferScramble. 0N/A * @returns IPRT status code. 0N/A * @param pv The pointer returned by the allocation function. 914N/A * @param cb The exact size given to the allocation function. 4031N/A * Allocates memory for sensitive data. 0N/A * Some effort will be taken to isolate the data from other memory allocation. 942N/A * Memory is always zeroed. 942N/A * @returns IPRT status code. 942N/A * @param ppvNew Where to return the pointer to the memory. * @param cb Number of bytes to allocate. * @param pszTag Allocation tag used for statistics and such. * Allocates memory for sensitive data. * Some effort will be taken to isolate the data from other memory allocation. * Memory is always zeroed. * @returns IPRT status code. * @param a_ppvNew Where to return the pointer to the memory. * @param a_cb Number of bytes to allocate. * Allocates memory for sensitive data. * Some effort will be taken to isolate the data from other memory allocation. * Memory is always zeroed. * @returns Pointer to the allocated memory. * @param cb Number of bytes to allocate. * @param pszTag Allocation tag used for statistics and such. * Allocates memory for sensitive data. * Some effort will be taken to isolate the data from other memory allocation. * Memory is always zeroed. * @returns Pointer to the allocated memory. * @param a_cb Number of bytes to allocate. * Reallocates memory allocated by RTMemSaferAllocZEx, RTMemSaferAllocZ, * RTMemSaferAllocZExTag, or RTMemSaferAllocZTag. * When extending the allocation, the new memory will be zeroed. When shrinking * the allocation the left over memory will be wiped clean using * The function follows the standard realloc behavior. * @returns IPRT status code. * @param cbOld The current allocation size. * @param pvOld The current allocation. * @param cbNew The size of the new allocation. * @param ppvNew Where to return the pointer to the new memory. * @param pszTag Allocation tag used for statistics and such. * Reallocates memory allocated by RTMemSaferAllocZEx, RTMemSaferAllocZ, * RTMemSaferAllocZExTag, or RTMemSaferAllocZTag. * When extending the allocation, the new memory will be zeroed. When shrinking * the allocation the left over memory will be wiped clean using * The function follows the standard realloc behavior. * @returns IPRT status code. * @param a_cbOld The current allocation size. * @param a_pvOld The current allocation. * @param a_cbNew The size of the new allocation. * @param a_ppvNew Where to return the pointer to the new memory. * Reallocates memory allocated by RTMemSaferAllocZ or RTMemSaferAllocZTag. * When extending the allocation, the new memory will be zeroed. When shrinking * the allocation the left over memory will be wiped clean using * The function follows the standard realloc behavior. * @returns Pointer to the allocated memory. * @param cbOld The current allocation size. * @param pvOld The current allocation. * @param cbNew The size of the new allocation. * @param pszTag Allocation tag used for statistics and such. * Reallocates memory allocated by RTMemSaferAllocZ or RTMemSaferAllocZTag. * When extending the allocation, the new memory will be zeroed. When shrinking * the allocation the left over memory will be wiped clean using * The function follows the standard realloc behavior. * @returns Pointer to the allocated memory. * @param a_cbOld The current allocation size. * @param a_pvOld The current allocation. * @param a_cbNew The size of the new allocation. * Frees memory allocated by RTMemSaferAllocZ* or RTMemSaferReallocZ*. * Before freeing the allocated memory, it will be wiped clean using * @returns Pointer to the allocated memory. * @param pv The allocation. * @param cb The allocation size.