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

[src]

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

[src]

OQS_init

OQS_API void OQS_init(void)

This currently only sets the values in the OQS_CPU_EXTENSIONS, and so has effect only when OQS_USE_CPU_EXTENSIONS and OQS_PORTABLE_BUILD are set.

[src]

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.

[src]

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.

[src]

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

void *

ptr

The start of the memory to free.

Macros

[src]

#define OQS_EXIT_IF_NULLPTR (x)

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

    do {                        \
        if ( (x) == (void*)0 )  \
            exit(EXIT_FAILURE); \
    } while (0)

[src]

#define OQS_OPENSSL_GUARD (x)

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)

[src]

#define SIZE_T_TO_INT_OR_EXIT (size_t_var_name, int_var_name)

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

[src]

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

[src]

#define UNUSED

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.