QSC Post Quantum Cryptographic Library 1.0.0.6c (A6)
A post quantum secure library written in Ansi C
 
Loading...
Searching...
No Matches
intutils.h File Reference

This file contains common integer manipulation and conversion functions. More...

#include "common.h"
#include "intrinsics.h"

Go to the source code of this file.

Macros

#define QSC_INTUTILS_KB_SIZE   1000ULL
 The number of bytes in a kilobyte.
 
#define QSC_INTUTILS_KIB_SIZE   1024ULL
 The number of bytes in a kibibyte.
 
#define QSC_INTUTILS_MB_SIZE   1000000ULL
 The number of bytes in a megabyte.
 
#define QSC_INTUTILS_MIB_SIZE   1048576ULL
 The number of bytes in a mebibyte.
 
#define QSC_INTUTILS_GB_SIZE   1000000000ULL
 The number of bytes in a gigabyte.
 
#define QSC_INTUTILS_GIB_SIZE   1073741824ULL
 The number of bytes in a gibibyte.
 
#define QSC_INTUTILS_TB_SIZE   1000000000000ULL
 The number of bytes in a terabyte.
 
#define QSC_INTUTILS_TIB_SIZE   1099511627776ULL
 The number of bytes in a tebibyte.
 
#define QSC_INTUTILS_PB_SIZE   1000000000000000ULL
 The number of bytes in a petabyte.
 
#define QSC_INTUTILS_PIB_SIZE   1125899906842624ULL
 The number of bytes in a pebibyte.
 
#define QSC_INTUTILS_EB_SIZE   1000000000000000000ULL
 The number of bytes in an exabyte.
 
#define QSC_INTUTILS_EIB_SIZE   1152921504606846976ULL
 The number of bytes in an exbibyte.
 

Functions

QSC_EXPORT_API bool qsc_intutils_are_equal8 (const uint8_t *a, const uint8_t *b, size_t length)
 Compare two arrays of 8-bit integers for equality. \ warning This function is not constant time. Use the qsc_intutils_verify for constant time operations.
 
QSC_EXPORT_API uint16_t qsc_intutils_be8to16 (const uint8_t *input)
 Convert an 8-bit integer array to a 16-bit big-endian integer.
 
QSC_EXPORT_API uint32_t qsc_intutils_be8to32 (const uint8_t *input)
 Convert an 8-bit integer array to a 32-bit big-endian integer.
 
QSC_EXPORT_API uint64_t qsc_intutils_be8to64 (const uint8_t *input)
 Convert an 8-bit integer array to a 64-bit big-endian integer.
 
QSC_EXPORT_API void qsc_intutils_be16to8 (uint8_t *output, uint16_t value)
 Convert a 16-bit integer to a big-endian 8-bit integer array.
 
QSC_EXPORT_API void qsc_intutils_be32to8 (uint8_t *output, uint32_t value)
 Convert a 32-bit integer to a big-endian 8-bit integer array.
 
QSC_EXPORT_API void qsc_intutils_be64to8 (uint8_t *output, uint64_t value)
 Convert a 64-bit integer to a big-endian 8-bit integer array.
 
QSC_EXPORT_API void qsc_intutils_be8increment (uint8_t *output, size_t otplen)
 Increment an 8-bit integer array as a segmented big-endian integer.
 
QSC_EXPORT_API size_t qsc_intutils_bit_reverse (size_t x, uint32_t bits)
 Reverse the bits of an integer.
 
QSC_EXPORT_API uint64_t qsc_intutils_bit_reverse_u64 (uint64_t x)
 Reverse the bits of a 64-bit integer.
 
QSC_EXPORT_API uint32_t qsc_intutils_bit_reverse_u32 (uint32_t x)
 Reverse the bits of a 32-bit integer.
 
QSC_EXPORT_API uint16_t qsc_intutils_bit_reverse_u16 (uint16_t x)
 Reverse the bits of a 16-bit integer.
 
QSC_EXPORT_API double qsc_intutils_calculate_abs (double a)
 Computes the absolute value of a double.
 
QSC_EXPORT_API double qsc_intutils_calculate_exp (double x)
 Computes the exponential function exp(x) using a Taylor series.
 
QSC_EXPORT_API double qsc_intutils_calculate_fabs (double x)
 Return the absolute value of a double.
 
QSC_EXPORT_API double qsc_intutils_calculate_log (double x)
 Computes the natural logarithm ln(x) without using math.h.
 
QSC_EXPORT_API double qsc_intutils_calculate_sqrt (double x)
 Computes the square root of a nonnegative number without using math.h.
 
QSC_EXPORT_API void qsc_intutils_clear8 (uint8_t *a, size_t count)
 Set an array of 8-bit integers to zero.
 
QSC_EXPORT_API void qsc_intutils_clear16 (uint16_t *a, size_t count)
 Set an array of 16-bit integers to zero.
 
QSC_EXPORT_API void qsc_intutils_clear32 (uint32_t *a, size_t count)
 Set an array of 32-bit integers to zero.
 
QSC_EXPORT_API void qsc_intutils_clear64 (uint64_t *a, size_t count)
 Set an array of 64-bit integers to zero.
 
QSC_EXPORT_API void qsc_intutils_cmov (uint8_t *dest, const uint8_t *source, size_t length, uint8_t cond)
 Perform a constant-time conditional move on two arrays of 8-bit integers.
 
QSC_EXPORT_API size_t qsc_intutils_expand_mask (size_t x)
 Expand an integer mask in constant time.
 
QSC_EXPORT_API bool qsc_intutils_are_equal (size_t x, size_t y)
 Check if two integers are equal.
 
QSC_EXPORT_API bool qsc_intutils_is_gte (size_t x, size_t y)
 Check if an integer is greater than or equal to another.
 
QSC_EXPORT_API void qsc_intutils_hex_to_bin (const char *hexstr, uint8_t *output, size_t otplen)
 Convert a hexadecimal string to a byte array.
 
QSC_EXPORT_API void qsc_intutils_bin_to_hex (const uint8_t *input, char *hexstr, size_t inplen)
 Convert a byte array to a hexadecimal string.
 
QSC_EXPORT_API void qsc_intutils_le8increment (uint8_t *output, size_t otplen)
 Increment an 8-bit integer array as a segmented little-endian integer.
 
QSC_EXPORT_API uint16_t qsc_intutils_le8to16 (const uint8_t *input)
 Convert an 8-bit integer array to a 16-bit little-endian integer.
 
QSC_EXPORT_API uint32_t qsc_intutils_le8to32 (const uint8_t *input)
 Convert an 8-bit integer array to a 32-bit little-endian integer.
 
QSC_EXPORT_API uint64_t qsc_intutils_le8to64 (const uint8_t *input)
 Convert an 8-bit integer array to a 64-bit little-endian integer.
 
QSC_EXPORT_API void qsc_intutils_le16to8 (uint8_t *output, uint16_t value)
 Convert a 16-bit integer to a little-endian 8-bit integer array.
 
QSC_EXPORT_API void qsc_intutils_le32to8 (uint8_t *output, uint32_t value)
 Convert a 32-bit integer to a little-endian 8-bit integer array.
 
QSC_EXPORT_API void qsc_intutils_le64to8 (uint8_t *output, uint64_t value)
 Convert a 64-bit integer to a little-endian 8-bit integer array.
 
QSC_EXPORT_API size_t qsc_intutils_max (size_t a, size_t b)
 Return the larger of two integers.
 
QSC_EXPORT_API size_t qsc_intutils_min (size_t a, size_t b)
 Return the smaller of two integers.
 
QSC_EXPORT_API uint32_t qsc_intutils_popcount32 (uint32_t v)
 Count the number of bits set in a 32-bit unsigned integer.
 
QSC_EXPORT_API uint32_t qsc_intutils_rotl32 (uint32_t value, size_t shift)
 Rotate an unsigned 32-bit integer to the left.
 
QSC_EXPORT_API uint64_t qsc_intutils_rotl64 (uint64_t value, size_t shift)
 Rotate an unsigned 64-bit integer to the left.
 
QSC_EXPORT_API uint32_t qsc_intutils_rotr32 (uint32_t value, size_t shift)
 Rotate an unsigned 32-bit integer to the right.
 
QSC_EXPORT_API uint64_t qsc_intutils_rotr64 (uint64_t value, size_t shift)
 Rotate an unsigned 64-bit integer to the right.
 
QSC_EXPORT_API int32_t qsc_intutils_verify (const uint8_t *a, const uint8_t *b, size_t length)
 Constant-time comparison of two 8-bit integer arrays.
 

Detailed Description

This file contains common integer manipulation and conversion functions.

The functions in this file provide a variety of operations on integers and arrays of integers, including byte-swapping, bit-reversal, rotation, constant-time comparisons, and conversions between different endianness. Additional utility functions such as computing the absolute value, exponential, natural logarithm, and square root are also provided using series approximations and iterative methods.

Function Documentation

◆ qsc_intutils_are_equal()

QSC_EXPORT_API bool qsc_intutils_are_equal ( size_t x,
size_t y )

Check if two integers are equal.

Parameters
x[size_t] The first integer.
y[size_t] The second integer.
Returns
[bool] Returns true if x equals y.

◆ qsc_intutils_are_equal8()

QSC_EXPORT_API bool qsc_intutils_are_equal8 ( const uint8_t * a,
const uint8_t * b,
size_t length )

Compare two arrays of 8-bit integers for equality. \ warning This function is not constant time. Use the qsc_intutils_verify for constant time operations.

Parameters
a[const uint8_t*] The first array.
b[const uint8_t*] The second array.
length[size_t] The number of bytes to compare.
Returns
[bool] Returns true if the arrays are equal.

◆ qsc_intutils_be16to8()

QSC_EXPORT_API void qsc_intutils_be16to8 ( uint8_t * output,
uint16_t value )

Convert a 16-bit integer to a big-endian 8-bit integer array.

Parameters
output[uint8_t*] The destination array.
value[uint16_t] The 16-bit integer.

◆ qsc_intutils_be32to8()

QSC_EXPORT_API void qsc_intutils_be32to8 ( uint8_t * output,
uint32_t value )

Convert a 32-bit integer to a big-endian 8-bit integer array.

Parameters
output[uint8_t*] The destination array.
value[uint32_t] The 32-bit integer.

◆ qsc_intutils_be64to8()

QSC_EXPORT_API void qsc_intutils_be64to8 ( uint8_t * output,
uint64_t value )

Convert a 64-bit integer to a big-endian 8-bit integer array.

Parameters
output[uint8_t*] The destination array.
value[uint64_t] The 64-bit integer.

◆ qsc_intutils_be8increment()

QSC_EXPORT_API void qsc_intutils_be8increment ( uint8_t * output,
size_t otplen )

Increment an 8-bit integer array as a segmented big-endian integer.

Parameters
output[uint8_t*] The counter array.
otplen[size_t] The length of the counter array.

◆ qsc_intutils_be8to16()

QSC_EXPORT_API uint16_t qsc_intutils_be8to16 ( const uint8_t * input)

Convert an 8-bit integer array to a 16-bit big-endian integer.

Parameters
input[const uint8_t*] The source 8-bit array.
Returns
[uint16_t] Returns the 16-bit big-endian integer.

◆ qsc_intutils_be8to32()

QSC_EXPORT_API uint32_t qsc_intutils_be8to32 ( const uint8_t * input)

Convert an 8-bit integer array to a 32-bit big-endian integer.

Parameters
input[const uint8_t*] The source 8-bit array.
Returns
[uint32_t] Returns the 32-bit big-endian integer.

◆ qsc_intutils_be8to64()

QSC_EXPORT_API uint64_t qsc_intutils_be8to64 ( const uint8_t * input)

Convert an 8-bit integer array to a 64-bit big-endian integer.

Parameters
input[const uint8_t*] The source 8-bit array.
Returns
[uint64_t] Returns the 64-bit big-endian integer.

◆ qsc_intutils_bin_to_hex()

QSC_EXPORT_API void qsc_intutils_bin_to_hex ( const uint8_t * input,
char * hexstr,
size_t inplen )

Convert a byte array to a hexadecimal string.

Parameters
input[const uint8_t*] The input array.
hexstr[char*] The output hexadecimal string; must be twice the size of the input array.
inplen[size_t] The length of the input array.

◆ qsc_intutils_bit_reverse()

QSC_EXPORT_API size_t qsc_intutils_bit_reverse ( size_t x,
uint32_t bits )

Reverse the bits of an integer.

Parameters
xThe integer.
bits[size_t] The number of bits to reverse.
Returns
[size_t] Returns the integer with its bits reversed.

◆ qsc_intutils_bit_reverse_u16()

QSC_EXPORT_API uint16_t qsc_intutils_bit_reverse_u16 ( uint16_t x)

Reverse the bits of a 16-bit integer.

Parameters
x[uint16_t] The 16-bit integer.
Returns
[uint16_t] Returns the 16-bit integer with its bits reversed.

◆ qsc_intutils_bit_reverse_u32()

QSC_EXPORT_API uint32_t qsc_intutils_bit_reverse_u32 ( uint32_t x)

Reverse the bits of a 32-bit integer.

Parameters
x[uint32_t] The 32-bit integer.
Returns
[uint32_t] Returns the 32-bit integer with its bits reversed.

◆ qsc_intutils_bit_reverse_u64()

QSC_EXPORT_API uint64_t qsc_intutils_bit_reverse_u64 ( uint64_t x)

Reverse the bits of a 64-bit integer.

Parameters
x[uint64_t] The 64-bit integer.
Returns
[uint64_t] Returns the 64-bit integer with its bits reversed.

◆ qsc_intutils_calculate_abs()

QSC_EXPORT_API double qsc_intutils_calculate_abs ( double a)

Computes the absolute value of a double.

Parameters
a[double] The input value.
Returns
[double] The absolute value of a.

◆ qsc_intutils_calculate_exp()

QSC_EXPORT_API double qsc_intutils_calculate_exp ( double x)

Computes the exponential function exp(x) using a Taylor series.

Special cases:

  • If x is NaN, the function returns NaN.
  • If x is greater than approximately 709.782712893384, the function returns positive infinity.
  • If x is less than approximately -745.133219101941, the function returns 0.

The function computes exp(x) via the Taylor series: exp(x) = 1 + x/1! + x^2/2! + x^3/3! + ... and stops when the absolute value of the term is less than a relative tolerance.

Parameters
x[double] The exponent.
Returns
[double] The computed exp(x) value.

◆ qsc_intutils_calculate_fabs()

QSC_EXPORT_API double qsc_intutils_calculate_fabs ( double x)

Return the absolute value of a double.

Parameters
x[double] The input double.
Returns
[double] Returns the absolute value.

◆ qsc_intutils_calculate_log()

QSC_EXPORT_API double qsc_intutils_calculate_log ( double x)

Computes the natural logarithm ln(x) without using math.h.

Special cases:

  • If x is NaN, returns NaN.
  • If x < 0, returns NaN.
  • If x == 0, returns negative infinity.
  • If x is extremely large, returns positive infinity.

For 0 < x < 1e300, this function first scales x into the interval [1,2) by repeatedly dividing or multiplying by 2, and then computes ln(x) using the series expansion:

ln(x) = 2 * ( y + y^3/3 + y^5/5 + ... )

where y = (x - 1)/(x + 1). The series continues until the current term falls below a fixed tolerance.

Parameters
x[double] The input value.
Returns
[double] The natural logarithm of x.

◆ qsc_intutils_calculate_sqrt()

QSC_EXPORT_API double qsc_intutils_calculate_sqrt ( double x)

Computes the square root of a nonnegative number without using math.h.

Special cases:

  • If x is negative, the function returns NaN.
  • If x is 0, the function returns 0.

For x > 0, Newton-Raphson iteration is used: guess_{n+1} = 0.5 * (guess_n + x / guess_n) The iteration stops when the absolute difference between successive guesses is less than a small fraction of the guess (relative tolerance).

Parameters
x[double] The input value.
Returns
[double] The square root of x, or NaN if x is negative.

◆ qsc_intutils_clear16()

QSC_EXPORT_API void qsc_intutils_clear16 ( uint16_t * a,
size_t count )

Set an array of 16-bit integers to zero.

Parameters
a[uint16_t*] The array to zeroize.
count[size_t] The number of elements to zeroize.

◆ qsc_intutils_clear32()

QSC_EXPORT_API void qsc_intutils_clear32 ( uint32_t * a,
size_t count )

Set an array of 32-bit integers to zero.

Parameters
a[uint32_t*] The array to zeroize.
count[size_t] The number of elements to zeroize.

◆ qsc_intutils_clear64()

QSC_EXPORT_API void qsc_intutils_clear64 ( uint64_t * a,
size_t count )

Set an array of 64-bit integers to zero.

Parameters
a[uint64_t*] The array to zeroize.
count[size_t] The number of elements to zeroize.

◆ qsc_intutils_clear8()

QSC_EXPORT_API void qsc_intutils_clear8 ( uint8_t * a,
size_t count )

Set an array of 8-bit integers to zero.

Parameters
a[uint8_t*] The array to zeroize.
count[size_t] The number of elements to zeroize.

◆ qsc_intutils_cmov()

QSC_EXPORT_API void qsc_intutils_cmov ( uint8_t * dest,
const uint8_t * source,
size_t length,
uint8_t cond )

Perform a constant-time conditional move on two arrays of 8-bit integers.

Parameters
dest[uint8_t*] The destination array.
source[const uint8_t*] The source array.
length[size_t] The number of bytes to move.
cond[uint8_t] The condition (1 to move, 0 to leave unchanged).

◆ qsc_intutils_expand_mask()

QSC_EXPORT_API size_t qsc_intutils_expand_mask ( size_t x)

Expand an integer mask in constant time.

Parameters
x[size_t] The N-bit word.
Returns
[size_t] Returns the expanded mask.

◆ qsc_intutils_hex_to_bin()

QSC_EXPORT_API void qsc_intutils_hex_to_bin ( const char * hexstr,
uint8_t * output,
size_t otplen )

Convert a hexadecimal string to a byte array.

Parameters
hexstr[const char*] The hexadecimal string.
output[uint8_t*] The output array.
otplen[size_t] The length of the output array.

◆ qsc_intutils_is_gte()

QSC_EXPORT_API bool qsc_intutils_is_gte ( size_t x,
size_t y )

Check if an integer is greater than or equal to another.

Parameters
x[size_t] The base integer.
y[size_t] The comparison integer.
Returns
[bool] Returns true if x is greater than or equal to y.

◆ qsc_intutils_le16to8()

QSC_EXPORT_API void qsc_intutils_le16to8 ( uint8_t * output,
uint16_t value )

Convert a 16-bit integer to a little-endian 8-bit integer array.

Parameters
output[uint8_t*] The destination array.
value[uint16_t] The 16-bit integer.

◆ qsc_intutils_le32to8()

QSC_EXPORT_API void qsc_intutils_le32to8 ( uint8_t * output,
uint32_t value )

Convert a 32-bit integer to a little-endian 8-bit integer array.

Parameters
output[uint8_t*] The destination array.
value[uint32_t] The 32-bit integer.

◆ qsc_intutils_le64to8()

QSC_EXPORT_API void qsc_intutils_le64to8 ( uint8_t * output,
uint64_t value )

Convert a 64-bit integer to a little-endian 8-bit integer array.

Parameters
output[uint8_t*] The destination array.
value[uint64_t] The 64-bit integer.

◆ qsc_intutils_le8increment()

QSC_EXPORT_API void qsc_intutils_le8increment ( uint8_t * output,
size_t otplen )

Increment an 8-bit integer array as a segmented little-endian integer.

Parameters
output[uint8_t*] The counter array.
otplen[size_t] The length of the counter array.

◆ qsc_intutils_le8to16()

QSC_EXPORT_API uint16_t qsc_intutils_le8to16 ( const uint8_t * input)

Convert an 8-bit integer array to a 16-bit little-endian integer.

Parameters
input[const uint8_t*] The source array.
Returns
[uint16_t] Returns the 16-bit little-endian integer.

◆ qsc_intutils_le8to32()

QSC_EXPORT_API uint32_t qsc_intutils_le8to32 ( const uint8_t * input)

Convert an 8-bit integer array to a 32-bit little-endian integer.

Parameters
input[const uint8_t*] The source array.
Returns
[uint32_t] Returns the 32-bit little-endian integer.

◆ qsc_intutils_le8to64()

QSC_EXPORT_API uint64_t qsc_intutils_le8to64 ( const uint8_t * input)

Convert an 8-bit integer array to a 64-bit little-endian integer.

Parameters
input[const uint8_t*] The source array.
Returns
[uint64_t] Returns the 64-bit little-endian integer.

◆ qsc_intutils_max()

QSC_EXPORT_API size_t qsc_intutils_max ( size_t a,
size_t b )

Return the larger of two integers.

Parameters
a[size_t] The first integer.
b[size_t] The second integer.
Returns
[size_t] Returns the larger integer.

◆ qsc_intutils_min()

QSC_EXPORT_API size_t qsc_intutils_min ( size_t a,
size_t b )

Return the smaller of two integers.

Parameters
a[size_t] The first integer.
b[size_t] The second integer.
Returns
[size_t] Returns the smaller integer.

◆ qsc_intutils_popcount32()

QSC_EXPORT_API uint32_t qsc_intutils_popcount32 ( uint32_t v)

Count the number of bits set in a 32-bit unsigned integer.

Parameters
v[uint32_t] The 32-bit integer.
Returns
[uint32_t] Returns the number of bits set.

◆ qsc_intutils_rotl32()

QSC_EXPORT_API uint32_t qsc_intutils_rotl32 ( uint32_t value,
size_t shift )

Rotate an unsigned 32-bit integer to the left.

Parameters
value[uint32_t] The integer value.
shift[size_t] The number of bits to shift.
Returns
[uint32_t] Returns the rotated integer.

◆ qsc_intutils_rotl64()

QSC_EXPORT_API uint64_t qsc_intutils_rotl64 ( uint64_t value,
size_t shift )

Rotate an unsigned 64-bit integer to the left.

Parameters
value[uint64_t] The integer value.
shift[size_t] The number of bits to shift.
Returns
[uint64_t] Returns the rotated integer.

◆ qsc_intutils_rotr32()

QSC_EXPORT_API uint32_t qsc_intutils_rotr32 ( uint32_t value,
size_t shift )

Rotate an unsigned 32-bit integer to the right.

Parameters
value[uint32_t] The integer value.
shift[size_t] The number of bits to shift.
Returns
[uint32_t] Returns the rotated integer.

◆ qsc_intutils_rotr64()

QSC_EXPORT_API uint64_t qsc_intutils_rotr64 ( uint64_t value,
size_t shift )

Rotate an unsigned 64-bit integer to the right.

Parameters
value[uint64_t] The integer value.
shift[size_t] The number of bits to shift.
Returns
[uint64_t] Returns the rotated integer.

◆ qsc_intutils_verify()

QSC_EXPORT_API int32_t qsc_intutils_verify ( const uint8_t * a,
const uint8_t * b,
size_t length )

Constant-time comparison of two 8-bit integer arrays.

Parameters
a[const uint8_t*] The first array.
b[const uint8_t*] The second array.
length[size_t] The number of bytes to compare.
Returns
[int32_t] Returns zero if the arrays are equivalent.