diff --git a/Makefile.am b/Makefile.am index 9e5b7dcce0ab9..21df09f41fb35 100644 --- a/Makefile.am +++ b/Makefile.am @@ -8,6 +8,7 @@ else JNI_LIB = endif include_HEADERS = include/secp256k1.h +include_HEADERS += include/secp256k1_preallocated.h noinst_HEADERS = noinst_HEADERS += src/scalar.h noinst_HEADERS += src/scalar_4x64.h diff --git a/include/secp256k1.h b/include/secp256k1.h index 77ca1b95c3168..e0d87a1883d2e 100644 --- a/include/secp256k1.h +++ b/include/secp256k1.h @@ -191,7 +191,8 @@ SECP256K1_API extern const secp256k1_context *secp256k1_context_no_precomp; /** Create a secp256k1 context object (in dynamically allocated memory). * * This function uses malloc to allocate memory. It is guaranteed that malloc is - * called at most once for every call of this function. + * called at most once for every call of this function. If you need to avoid dynamic + * memory allocation entirely, see the functions in secp256k1_preallocated.h. * * Returns: a newly created context object. * In: flags: which parts of the context to initialize. @@ -205,7 +206,8 @@ SECP256K1_API secp256k1_context* secp256k1_context_create( /** Copy a secp256k1 context object (into dynamically allocated memory). * * This function uses malloc to allocate memory. It is guaranteed that malloc is - * called at most once for every call of this function. + * called at most once for every call of this function. If you need to avoid dynamic + * memory allocation entirely, see the functions in secp256k1_preallocated.h. * * Returns: a newly created context object. * Args: ctx: an existing context to copy (cannot be NULL) @@ -230,81 +232,6 @@ SECP256K1_API secp256k1_context* secp256k1_context_clone( SECP256K1_API void secp256k1_context_destroy( secp256k1_context* ctx ); -/** Determine the memory size of a secp256k1 context object to be created in - * caller-provided memory. - * - * The purpose of this function is to determine how much memory must be provided - * to secp256k1_context_preallocated_create. - * - * Returns: the required size of the caller-provided memory block - * In: flags: which parts of the context to initialize. - */ - -SECP256K1_API size_t secp256k1_context_preallocated_size( - unsigned int flags -) SECP256K1_WARN_UNUSED_RESULT; - -/** Create a secp256k1 context object in caller-provided memory. - * - * Returns: a newly created context object. - * In: prealloc: a pointer to a rewritable contiguous block of memory of - * size at least secp256k1_context_preallocated_size(flags) - * bytes, suitably aligned to hold an object of any type - * (cannot be NULL) - * flags: which parts of the context to initialize. - * - * See also secp256k1_context_randomize. - */ -SECP256K1_API secp256k1_context* secp256k1_context_preallocated_create( - void* prealloc, - unsigned int flags -) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT; - -/** Determine the memory size of a secp256k1 context object to be copied into - * caller-provided memory. - * - * The purpose of this function is to determine how much memory must be provided - * to secp256k1_context_preallocated_clone when copying the context ctx. - * - * Returns: the required size of the caller-provided memory block. - * In: ctx: an existing context to copy (cannot be NULL) - */ -SECP256K1_API size_t secp256k1_context_preallocated_clone_size( - const secp256k1_context* ctx -) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT; - -/** Copy a secp256k1 context object into caller-provided memory. - * - * Returns: a newly created context object. - * Args: ctx: an existing context to copy (cannot be NULL) - * In: prealloc: a pointer to a rewritable contiguous block of memory of - * size at least secp256k1_context_preallocated_size(flags) - * bytes, suitably aligned to hold an object of any type - * (cannot be NULL) - */ -SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone( - const secp256k1_context* ctx, - void* prealloc -) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_WARN_UNUSED_RESULT; - -/** Destroy a secp256k1 context object that has been created in - * caller-provided memory. - * - * The context pointer may not be used afterwards. - * - * The context to destroy must have been created using - * secp256k1_context_preallocated_create or secp256k1_context_preallocated_clone. - * If the context has instead been created using secp256k1_context_create or - * secp256k1_context_clone, the behaviour is undefined. In that case, - * secp256k1_context_destroy must be used instead. - * - * Args: ctx: an existing context to destroy, constructed using - * secp256k1_context_preallocated_create or - * secp256k1_context_preallocated_clone (cannot be NULL) - */ -SECP256K1_API void secp256k1_context_preallocated_destroy( - secp256k1_context* ctx -); /** Set a callback function to be called when an illegal argument is passed to * an API call. It will only trigger for violations that are mentioned diff --git a/include/secp256k1_preallocated.h b/include/secp256k1_preallocated.h new file mode 100644 index 0000000000000..77426ee786fd5 --- /dev/null +++ b/include/secp256k1_preallocated.h @@ -0,0 +1,98 @@ +#ifndef SECP256K1_PREALLOCATED_H +#define SECP256K1_PREALLOCATED_H + +#include "secp256k1.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* The module provided by this header file is intended for settings in which it + * is not possible or desirable to rely on dynamic memory allocation. It provides + * functions for creating, cloning, and destroying secp256k1 context objects in a + * contiguous fixed-size block of memory provided by the caller. + * + * It is guaranteed that functions in this module will not call malloc or its + * friends realloc, calloc, and free. + */ + +/** Determine the memory size of a secp256k1 context object to be created in + * caller-provided memory. + * + * The purpose of this function is to determine how much memory must be provided + * to secp256k1_context_preallocated_create. + * + * Returns: the required size of the caller-provided memory block + * In: flags: which parts of the context to initialize. + */ +SECP256K1_API size_t secp256k1_context_preallocated_size( + unsigned int flags +) SECP256K1_WARN_UNUSED_RESULT; + +/** Create a secp256k1 context object in caller-provided memory. + * + * Returns: a newly created context object. + * In: prealloc: a pointer to a rewritable contiguous block of memory of + * size at least secp256k1_context_preallocated_size(flags) + * bytes, suitably aligned to hold an object of any type + * (cannot be NULL) + * flags: which parts of the context to initialize. + * + * See also secp256k1_context_randomize. + */ +SECP256K1_API secp256k1_context* secp256k1_context_preallocated_create( + void* prealloc, + unsigned int flags +) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT; + +/** Determine the memory size of a secp256k1 context object to be copied into + * caller-provided memory. + * + * The purpose of this function is to determine how much memory must be provided + * to secp256k1_context_preallocated_clone when copying the context ctx. + * + * Returns: the required size of the caller-provided memory block. + * In: ctx: an existing context to copy (cannot be NULL) + */ +SECP256K1_API size_t secp256k1_context_preallocated_clone_size( + const secp256k1_context* ctx +) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT; + +/** Copy a secp256k1 context object into caller-provided memory. + * + * Returns: a newly created context object. + * Args: ctx: an existing context to copy (cannot be NULL) + * In: prealloc: a pointer to a rewritable contiguous block of memory of + * size at least secp256k1_context_preallocated_size(flags) + * bytes, suitably aligned to hold an object of any type + * (cannot be NULL) + */ +SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone( + const secp256k1_context* ctx, + void* prealloc +) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_WARN_UNUSED_RESULT; + +/** Destroy a secp256k1 context object that has been created in + * caller-provided memory. + * + * The context pointer may not be used afterwards. + * + * The context to destroy must have been created using + * secp256k1_context_preallocated_create or secp256k1_context_preallocated_clone. + * If the context has instead been created using secp256k1_context_create or + * secp256k1_context_clone, the behaviour is undefined. In that case, + * secp256k1_context_destroy must be used instead. + * + * Args: ctx: an existing context to destroy, constructed using + * secp256k1_context_preallocated_create or + * secp256k1_context_preallocated_clone (cannot be NULL) + */ +SECP256K1_API void secp256k1_context_preallocated_destroy( + secp256k1_context* ctx +); + +#ifdef __cplusplus +} +#endif + +#endif /* SECP256K1_PREALLOCATED_H */ diff --git a/src/secp256k1.c b/src/secp256k1.c index 9fdd0c47c7889..edfe1f397270a 100644 --- a/src/secp256k1.c +++ b/src/secp256k1.c @@ -5,6 +5,7 @@ **********************************************************************/ #include "include/secp256k1.h" +#include "include/secp256k1_preallocated.h" #include "util.h" #include "num_impl.h" diff --git a/src/tests.c b/src/tests.c index b0d5af7d2e44b..908858bf388d6 100644 --- a/src/tests.c +++ b/src/tests.c @@ -16,6 +16,7 @@ #include "secp256k1.c" #include "include/secp256k1.h" +#include "include/secp256k1_preallocated.h" #include "testrand_impl.h" #ifdef ENABLE_OPENSSL_TESTS