src/common/common.h
Utility functions for use in liboqs.
SPDX-License-Identifier: MIT
Includes
#include <limits.h>
#include <stdint.h>
#include <stdlib.h>
#include <oqs/oqsconfig.h>
Enumeration Types
enum OQS_STATUS
Represents return values from functions.
Callers should compare with the symbol rather than the individual value. For example,
ret = OQS_KEM_encaps(...); if (ret == OQS_SUCCESS) { ... }
rather than
if (!OQS_KEM_encaps(...) { ... }
Enumeration values
OQS_ERROR = -1 | Used to indicate that some undefined error occurred. |
OQS_SUCCESS = 0 | Used to indicate successful return from function. |
OQS_EXTERNAL_LIB_ERROR_OPENSSL = 50 | Used to indicate failures in external libraries (e.g., OpenSSL). |
Functions
OQS_API void | OQS_init(void) |
OQS_API void | OQS_MEM_cleanse(void *ptr, size_t len) |
OQS_API void | OQS_MEM_secure_free(void *ptr, size_t len) |
OQS_API void | OQS_MEM_insecure_free(void *ptr) |
OQS_MEM_cleanse
OQS_API void OQS_MEM_cleanse(void *ptr, size_t len)
Zeros out len
bytes of memory starting at ptr
.
Designed to be protected against optimizing compilers which try to remove "unnecessary" operations. Should be used for all buffers containing secret data.
Parameters
void * | ptr | The start of the memory to zero out. |
size_t | len | The number of bytes to zero out. |
OQS_MEM_secure_free
OQS_API void OQS_MEM_secure_free(void *ptr, size_t len)
Zeros out len
bytes of memory starting at ptr
, then frees ptr
.
Can be called with ptr = NULL
, in which case no operation is performed.
Designed to be protected against optimizing compilers which try to remove "unnecessary" operations. Should be used for all buffers containing secret data.
Parameters
void * | ptr | The start of the memory to zero out and free. |
size_t | len | The number of bytes to zero out. |
Macros
Macro for terminating the program if x is a null pointer. do { \ if ( (x) == (void*)0 ) \ exit(EXIT_FAILURE); \ } while (0) |
This macro is intended to replace those assert()s involving side-effecting statements in aes/aes_ossl.c. assert() becomes a no-op when -DNDEBUG is defined, which causes compilation failures when the statement being checked also results in side-effects. This is a temporary workaround until a better error handling strategy is developed. do { \ if( 1 != (x) ) { \ exit(EXIT_FAILURE); \ } \ } while (0) |
Certain functions (such as OQS_randombytes_openssl in src/rand/rand.c) take in a size_t parameter, but can only handle values up to INT_MAX for those parameters. This macro is a temporary workaround for such functions. int int_var_name = 0; \ if (size_t_var_name <= INT_MAX) { \ int_var_name = (int)size_t_var_name; \ } else { \ exit(EXIT_FAILURE); \ } |
Defines which functions should be exposed outside the LibOQS library By default the visibility of all the symbols is defined to "hidden" Only the library API should be marked as default Example: OQS_API return_value function_name(void); |
Macros that indicates a function argument may be unused. Used to comply with an API specification but when an implementation doesn't actually use the argument and we'd get a compiler warning otherwise. |