secure_allocator.h

00001 /*
00002  * Copyright (c) 2016, ARM Limited, All Rights Reserved
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00006  * not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00013  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef __SECURE_ALLOCATOR_H__
00018 #define __SECURE_ALLOCATOR_H__
00019 
00020 #include <stdint.h>
00021 #include <stddef.h>
00022 
00023 #ifdef __cplusplus
00024 extern "C" {
00025 #endif
00026 
00027 /** Contains the allocator data and backing page table. */
00028 typedef void * SecureAllocator;
00029 
00030 /** Create an allocator in-place in an existing pool without using pages.
00031  * Use this to turn statically allocated memory into a heap.
00032  * Or allocate a large piece of memory and then turn that into a heap.
00033  *
00034  * @param mem   Pointer to the origin of the memory pool
00035  * @param bytes Length of the memory pool in bytes
00036  * @returns the allocator or `NULL` on failure
00037  */
00038 SecureAllocator secure_allocator_create_with_pool(
00039     void * mem,
00040     size_t bytes);
00041 
00042 /** Create an allocator using pages from the page heap.
00043  * Use this to request secure dynamic memory for your process.
00044  * Note that this memory is not guaranteed to be consecutive, therefore you
00045  * must specify the maximum allocation size that you plan to use in this
00046  * allocator. This function will then compute the number and size of required
00047  * pages and request them from the secure page heap.
00048  *
00049  * @param total_size          The minimal total size of the heap
00050  * @param maximum_malloc_size The largest size to be allocated in one chunk
00051  * @returns the allocator or `NULL` on failure (out of memory,
00052  *          maximum malloc size cannot be fulfilled)
00053  */
00054 SecureAllocator secure_allocator_create_with_pages(
00055     size_t total_size,
00056     size_t maximum_malloc_size);
00057 
00058 /** Destroy the allocator and free the backing pages.
00059  * An attempt to destroy a memory-pool backed allocator will fail and return
00060  * with an error code.
00061  *
00062  * @retval 0  Allocator successfully destroyed.
00063  * @retval -1 Allocator is static (memory-pool), or freeing memory pages failed.
00064  */
00065 int secure_allocator_destroy(
00066     SecureAllocator allocator);
00067 
00068 /** Drop-in for `malloc`. */
00069 void * secure_malloc(
00070     SecureAllocator allocator,
00071     size_t size);
00072 
00073 /** Drop-in for `realloc`. */
00074 void * secure_realloc(
00075     SecureAllocator allocator,
00076     void * ptr,
00077     size_t size);
00078 
00079 /** Drop-in for `free`. */
00080 void secure_free(
00081     SecureAllocator allocator,
00082     void * ptr);
00083 
00084 #ifdef __cplusplus
00085 }   /* extern "C" */
00086 #endif
00087 
00088 #endif  /* __SECURE_ALLOCATOR_H__ */