liboqs
Loading...
Searching...
No Matches
common.h File Reference

Utility functions for use in liboqs. More...

#include <limits.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
#include <oqs/oqsconfig.h>

Go to the source code of this file.

Macros

#define OQS_EXIT_IF_NULLPTR(x, loc)
 
#define SIZE_T_TO_INT_OR_EXIT(size_t_var_name, int_var_name)
 
#define OQS_API   __attribute__((visibility("default")))
 

Enumerations

enum  OQS_STATUS { OQS_ERROR = -1 , OQS_SUCCESS = 0 , OQS_EXTERNAL_LIB_ERROR_OPENSSL = 50 }
 
enum  OQS_CPU_EXT {
  OQS_CPU_EXT_INIT , OQS_CPU_EXT_ADX , OQS_CPU_EXT_AES , OQS_CPU_EXT_AVX ,
  OQS_CPU_EXT_AVX2 , OQS_CPU_EXT_AVX512 , OQS_CPU_EXT_BMI1 , OQS_CPU_EXT_BMI2 ,
  OQS_CPU_EXT_PCLMULQDQ , OQS_CPU_EXT_VPCLMULQDQ , OQS_CPU_EXT_POPCNT , OQS_CPU_EXT_SSE ,
  OQS_CPU_EXT_SSE2 , OQS_CPU_EXT_SSE3 , OQS_CPU_EXT_ARM_AES , OQS_CPU_EXT_ARM_SHA2 ,
  OQS_CPU_EXT_ARM_SHA3 , OQS_CPU_EXT_ARM_NEON , OQS_CPU_EXT_COUNT
}
 

Functions

OQS_API int OQS_CPU_has_extension (OQS_CPU_EXT ext)
 
OQS_API void OQS_init (void)
 
OQS_API void OQS_destroy (void)
 
OQS_API const char * OQS_version (void)
 
OQS_API int OQS_MEM_secure_bcmp (const void *a, const void *b, size_t len)
 
OQS_API void OQS_MEM_cleanse (void *ptr, size_t len)
 
void * OQS_MEM_checked_malloc (size_t len)
 
void * OQS_MEM_checked_aligned_alloc (size_t alignment, size_t size)
 
OQS_API void OQS_MEM_secure_free (void *ptr, size_t len)
 
OQS_API void OQS_MEM_insecure_free (void *ptr)
 
void * OQS_MEM_aligned_alloc (size_t alignment, size_t size)
 
void OQS_MEM_aligned_free (void *ptr)
 

Detailed Description

Utility functions for use in liboqs.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ OQS_API

#define OQS_API   __attribute__((visibility("default")))

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);

◆ OQS_EXIT_IF_NULLPTR

#define OQS_EXIT_IF_NULLPTR ( x,
loc )
Value:
do { \
if ( (x) == (void*)0 ) { \
fprintf(stderr, "Unexpected NULL returned from %s API. Exiting.\n", loc); \
exit(EXIT_FAILURE); \
} \
} while (0)

Macro for terminating the program if x is a null pointer.

◆ SIZE_T_TO_INT_OR_EXIT

#define SIZE_T_TO_INT_OR_EXIT ( size_t_var_name,
int_var_name )
Value:
int int_var_name = 0; \
if (size_t_var_name <= INT_MAX) { \
int_var_name = (int)size_t_var_name; \
} else { \
exit(EXIT_FAILURE); \
}

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. 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.

Enumeration Type Documentation

◆ OQS_CPU_EXT

CPU runtime detection flags

◆ OQS_STATUS

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(...) { ... }
Enumerator
OQS_ERROR 

Used to indicate that some undefined error occurred.

OQS_SUCCESS 

Used to indicate successful return from function.

OQS_EXTERNAL_LIB_ERROR_OPENSSL 

Used to indicate failures in external libraries (e.g., OpenSSL).

Function Documentation

◆ OQS_CPU_has_extension()

OQS_API int OQS_CPU_has_extension ( OQS_CPU_EXT ext)

Checks if the CPU supports a given extension

Returns
1 if the given CPU extension is available, 0 otherwise.

◆ OQS_destroy()

OQS_API void OQS_destroy ( void )

This function frees prefetched OpenSSL objects

◆ OQS_init()

OQS_API void OQS_init ( void )

This currently sets the values in the OQS_CPU_EXTENSIONS and prefetches the OpenSSL objects if necessary.

◆ OQS_MEM_aligned_alloc()

void * OQS_MEM_aligned_alloc ( size_t alignment,
size_t size )

Internal implementation of C11 aligned_alloc to work around compiler quirks.

Allocates size bytes of uninitialized memory with a base pointer that is a multiple of alignment. Alignment must be a power of two and a multiple of sizeof(void *). Size must be a multiple of alignment.

Note
The allocated memory should be freed with OQS_MEM_aligned_free when it is no longer needed.

◆ OQS_MEM_aligned_free()

void OQS_MEM_aligned_free ( void * ptr)

Free memory allocated with OQS_MEM_aligned_alloc.

◆ OQS_MEM_checked_aligned_alloc()

void * OQS_MEM_checked_aligned_alloc ( size_t alignment,
size_t size )

Allocates memory of a specified size and alignment and checks for successful allocation.

This function attempts to allocate a block of memory with the specified size and alignment. If the allocation is successful, it returns a pointer to the memory block. If the allocation fails, it prints an error message to stderr and terminates the program.

Alignment must be a power of two and a multiple of sizeof(void *).

Parameters
[in]alignmentThe alignment of the memory block to allocate.
[in]sizeThe size of the memory block to allocate, in bytes.
Returns
A pointer to the allocated memory block if the allocation is successful.
Note
This function is intended to be used when the allocation must succeed, and failure to allocate memory is considered a fatal error. As such, it does not return if the allocation fails, but instead terminates the program with an exit status indicating failure.
The memory block returned by this function is not initialized. The caller is responsible for initializing the memory if required.
The allocated memory should be freed with OQS_MEM_aligned_free when it is no longer needed.

◆ OQS_MEM_checked_malloc()

void * OQS_MEM_checked_malloc ( size_t len)

Allocates memory of a specified size and checks for successful allocation.

This function attempts to allocate a block of memory of the specified size. If the allocation is successful, it returns a pointer to the beginning of the memory block. If the allocation fails, it prints an error message to stderr and terminates the program.

Parameters
[in]lenThe size of the memory block to allocate, in bytes.
Returns
A pointer to the allocated memory block if the allocation is successful.
Note
This function is intended to be used when the allocation must succeed, and failure to allocate memory is considered a fatal error. As such, it does not return if the allocation fails, but instead terminates the program with an exit status indicating failure.
The memory block returned by this function is not initialized. The caller is responsible for initializing the memory if required.
The allocated memory should be freed using the standard free function when it is no longer needed.

◆ 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
[in]ptrThe start of the memory to zero out.
[in]lenThe number of bytes to zero out.

◆ OQS_MEM_insecure_free()

OQS_API void OQS_MEM_insecure_free ( void * ptr)

Frees ptr.

Can be called with ptr = NULL, in which case no operation is performed.

Should only be used on non-secret data.

Parameters
[in]ptrThe start of the memory to free.

◆ OQS_MEM_secure_bcmp()

OQS_API int OQS_MEM_secure_bcmp ( const void * a,
const void * b,
size_t len )

Constant time comparison of byte sequences a and b of length len. Returns 0 if the byte sequences are equal or if len=0. Returns 1 otherwise.

Parameters
[in]aA byte sequence of length at least len.
[in]bA byte sequence of length at least len.
[in]lenThe number of bytes to compare.

◆ 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
[in]ptrThe start of the memory to zero out and free.
[in]lenThe number of bytes to zero out.

◆ OQS_version()

OQS_API const char * OQS_version ( void )

Return library version string.