13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * IPRT - Memory Allocate for Sensitive Data.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Copyright (C) 2006-2014 Oracle Corporation
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * available from http://www.virtualbox.org. This file is free software;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * you can redistribute it and/or modify it under the terms of the GNU
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * General Public License (GPL) as published by the Free Software
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The contents of this file may alternatively be used under the terms
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * of the Common Development and Distribution License Version 1.0
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * VirtualBox OSE distribution, in which case the provisions of the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * CDDL are applicable instead of those of the GPL.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * You may elect to license modified versions of this file under the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * terms and conditions of either the GPL or the CDDL or both.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync/** @defgroup grp_rt_memsafer RTMemSafer - Memory Allocator for Sensitive Data
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @ingroup grp_rt
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * This API doesn't provide 100% secure storage, it only provider more secure
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * and safer storage. Thus the API isn't called RTMemSafe because you cannot
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * assume the data is safe against all kinds of extraction methods.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The API guarantee that the memory won't be returned to the system containing
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * any of the information you put there. It will be repeatedly wiped after use.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The API tries to isolate your data from other information stored in the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * process/system. How well this is done depends on the implementation. The
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * more complicated implementations will provide protection against heartbleed
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * like bugs where pieces of the heap is copied onto the wire.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The more hardened implementations of the API will also do their best to
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * prevent the memory from ending up in process dumps or being readable by
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * debuggers.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Finally, two functions are provided for scrambling the sensitive memory while
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * it's not in use.
bcb3083f42e955d186649946e002930e75134f8dvboxsync/** @name RTMEMSAFER_F_XXX
bcb3083f42e955d186649946e002930e75134f8dvboxsync/** Require the memory to not hit the page file.
bcb3083f42e955d186649946e002930e75134f8dvboxsync * @remarks Makes not guarantees with regards to hibernation /
bcb3083f42e955d186649946e002930e75134f8dvboxsync * suspend-to-disk. */
bcb3083f42e955d186649946e002930e75134f8dvboxsync#define RTMEMSAFER_F_REQUIRE_NOT_PAGABLE RT_BIT_32(0)
bcb3083f42e955d186649946e002930e75134f8dvboxsync/** Mask of valid bits. */
bcb3083f42e955d186649946e002930e75134f8dvboxsync#define RTMEMSAFER_F_VALID_MASK UINT32_C(0x00000001)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Scrambles memory allocated by RTMemSaferAllocZEx and associates after use.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Call this when the sensitive data isn't actively being used. It will at a
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * minimum make sure the data is slightly scrambled, how hard it is to unbutton
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * is dependent on which implementation is used and available host support.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The user must synchronize calls to RTMemSaferScramble and
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemSaferUnscramble, this memory allocator provides no help and keeps no
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * state information around.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns IPRT status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pv The pointer returned by the allocation function.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cb The exact size given to the allocation function.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncRTDECL(int) RTMemSaferScramble(void *pv, size_t cb);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Unscrambles memory allocated by RTMemSaferAllocZEx and associates before use.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * This undoes the effect of RTMemSaferScramble.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns IPRT status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pv The pointer returned by the allocation function.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cb The exact size given to the allocation function.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncRTDECL(int) RTMemSaferUnscramble(void *pv, size_t cb);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Allocates memory for sensitive data.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Some effort will be taken to isolate the data from other memory allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Memory is always zeroed.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns IPRT status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param ppvNew Where to return the pointer to the memory.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cb Number of bytes to allocate.
bcb3083f42e955d186649946e002930e75134f8dvboxsync * @param fFlags Flags for controlling the allocation, see
bcb3083f42e955d186649946e002930e75134f8dvboxsync * RTMEMSAFER_F_XXX.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszTag Allocation tag used for statistics and such.
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsyncRTDECL(int) RTMemSaferAllocZExTag(void **ppvNew, size_t cb, uint32_t fFlags, const char *pszTag) RT_NO_THROW;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Allocates memory for sensitive data.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Some effort will be taken to isolate the data from other memory allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Memory is always zeroed.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns IPRT status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_ppvNew Where to return the pointer to the memory.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_cb Number of bytes to allocate.
bcb3083f42e955d186649946e002930e75134f8dvboxsync * @param a_fFlags Flags for controlling the allocation, see
bcb3083f42e955d186649946e002930e75134f8dvboxsync * RTMEMSAFER_F_XXX.
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsync#define RTMemSaferAllocZEx(a_ppvNew, a_cb, a_fFlags) RTMemSaferAllocZExTag(a_ppvNew, a_cb, a_fFlags, RTMEM_TAG)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Allocates memory for sensitive data.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Some effort will be taken to isolate the data from other memory allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Memory is always zeroed.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns Pointer to the allocated memory.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cb Number of bytes to allocate.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszTag Allocation tag used for statistics and such.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncRTDECL(void *) RTMemSaferAllocZTag(size_t cb, const char *pszTag) RT_NO_THROW;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Allocates memory for sensitive data.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Some effort will be taken to isolate the data from other memory allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Memory is always zeroed.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns Pointer to the allocated memory.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_cb Number of bytes to allocate.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync#define RTMemSaferAllocZ(a_cb) RTMemSaferAllocZTag(a_cb, RTMEM_TAG)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Reallocates memory allocated by RTMemSaferAllocZEx, RTMemSaferAllocZ,
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemSaferAllocZExTag, or RTMemSaferAllocZTag.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * When extending the allocation, the new memory will be zeroed. When shrinking
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * the allocation the left over memory will be wiped clean using
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemWipeThorougly.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The function follows the standard realloc behavior.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns IPRT status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cbOld The current allocation size.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pvOld The current allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cbNew The size of the new allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param ppvNew Where to return the pointer to the new memory.
bcb3083f42e955d186649946e002930e75134f8dvboxsync * @param a_fFlags Flags for controlling the allocation, see
bcb3083f42e955d186649946e002930e75134f8dvboxsync * RTMEMSAFER_F_XXX. It is not permitted to drop saftely
bcb3083f42e955d186649946e002930e75134f8dvboxsync * requirments after the initial allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszTag Allocation tag used for statistics and such.
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsyncRTDECL(int) RTMemSaferReallocZExTag(size_t cbOld, void *pvOld, size_t cbNew, void **ppvNew, uint32_t fFlags, const char *pszTag) RT_NO_THROW;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Reallocates memory allocated by RTMemSaferAllocZEx, RTMemSaferAllocZ,
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemSaferAllocZExTag, or RTMemSaferAllocZTag.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * When extending the allocation, the new memory will be zeroed. When shrinking
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * the allocation the left over memory will be wiped clean using
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemWipeThorougly.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The function follows the standard realloc behavior.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns IPRT status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_cbOld The current allocation size.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_pvOld The current allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_cbNew The size of the new allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_ppvNew Where to return the pointer to the new memory.
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsync * @param a_fFlags Flags for controlling the allocation. See RTMEMSAFER_ALLOC_EX_FLAGS_* defines,
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsync * this takes only effect when allocating completely new memory, for extending or
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsync * shrinking existing allocations the flags of the allocation take precedence.
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsync#define RTMemSaferReallocZEx(a_cbOld, a_pvOld, a_cbNew, a_ppvNew, a_fFlags) \
9236bebed5c5902b30061ea6378bba30ef0577cbvboxsync RTMemSaferReallocZExTag(a_cbOld, a_pvOld, a_cbNew, a_ppvNew, a_fFlags, RTMEM_TAG)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Reallocates memory allocated by RTMemSaferAllocZ or RTMemSaferAllocZTag.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * When extending the allocation, the new memory will be zeroed. When shrinking
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * the allocation the left over memory will be wiped clean using
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemWipeThorougly.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The function follows the standard realloc behavior.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns Pointer to the allocated memory.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cbOld The current allocation size.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pvOld The current allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cbNew The size of the new allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszTag Allocation tag used for statistics and such.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncRTDECL(void *) RTMemSaferReallocZTag(size_t cbOld, void *pvOld, size_t cbNew, const char *pszTag) RT_NO_THROW;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Reallocates memory allocated by RTMemSaferAllocZ or RTMemSaferAllocZTag.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * When extending the allocation, the new memory will be zeroed. When shrinking
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * the allocation the left over memory will be wiped clean using
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemWipeThorougly.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The function follows the standard realloc behavior.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns Pointer to the allocated memory.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_cbOld The current allocation size.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_pvOld The current allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param a_cbNew The size of the new allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync#define RTMemSaferReallocZ(a_cbOld, a_pvOld, a_cbNew) RTMemSaferReallocZTag(a_cbOld, a_pvOld, a_cbNew, RTMEM_TAG)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Frees memory allocated by RTMemSaferAllocZ* or RTMemSaferReallocZ*.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Before freeing the allocated memory, it will be wiped clean using
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * RTMemWipeThorougly.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns Pointer to the allocated memory.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pv The allocation.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param cb The allocation size.