c4e_elements.h File Reference

(Version 568)

Big Number declarations. More...

#include "c4e_sys.h"

Include dependency graph for c4e_elements.h:

Data Structures
struct	C4eElement
	Element of a set/field, a big number or binary polynomial. More...
struct	C4eElemOsp
	An octet string conversion capable element, having an exact length specification (in bytes). More...
struct	C4eElemPair
	A pair of elements and it's attribute. More...
struct	C4eElemTriple
	A triple of elements and it's attribute(s). More...
Defines
#define	C4E_ELEM_ASGN_MEM(elem, digmem)
	Assign digits memory to an element.
#define	C4E_ELEM_DIGITS_NUM(bytes)
	Calculation of equivalent number of digits (of type C4eArchDigit) from number of bytes.
#define	C4E_ELEM_IS_ZERO(x)
	Checks whether an element is zero (or not).
#define	C4E_ELEM_IS_NZERO(x)
	Checks whether an element is NOT zero.
#define	C4E_ELEM_SET_ZERO(x)
	Sets an element to zero.
#define	C4E_ELEM_IS_ONE(x)
	Checks whether an element is one.
#define	C4E_ELEM_SET_ONE(x)
	Sets an element to one.
#define	C4E_ELEM_IS_EVEN(elem)
	Tests if an element is even.
#define	C4E_ELEM_IS_ODD(elem)
	Tests if an element is odd.
#define	C4E_ELEM_IS_NORM(x)
	Tests if an element is normalized.
#define	C4E_ELEM_MUL2(x)
	Multiplication of a set/field element by two.
#define	C4E_ELEM_DIV2(x)
	Division of a set/field element by two.
#define	C4E_ELEM_ASSERT_IN(x)
	Assert an elements pointer, which is a input parameter.
#define	C4E_ELEM_ASSERT_PTR(x)
	Assert the pointer members of an elements structure.
#define	C4E_ELEM_ASSERT_NORM(x)
	Assert an element is normalized.
#define	C4E_ELEM_ASSERT_NZERO(x)
	Assert an element is none-zero.
Enumerations
enum	C4eElemCmp { C4eElemCmpEQ, C4eElemCmpLT, C4eElemCmpGT }
	Elements (big numbers or binary polynomials) comparision result. More...
Functions
C4eArchDigit	c4e_elem_msb (C4E_CONST C4eElement *x)
	Returns a (single) bit mask for the most significant bit (which is one, in most significant digit) of element `x`.
C4eArchSize	c4e_elem_bits (C4E_CONST C4eElement *x)
	This function returns the number of significant bits in an element.
void	c4e_elem_norm (C4eElement *x)
	Normalization of a set/field element, means removal of leading zero digits.
void	c4e_elem_cpy (C4E_CONST C4eElement C4E_RESTRICT src, C4eElement C4E_RESTRICT dst)
	Copies a set/field element.
void	c4e_elem_swap (C4eElement C4E_RESTRICT elem1, C4eElement C4E_RESTRICT elem2)
	Swaps all digits of two set/field elements (and changes it's size).
void	c4e_elem_fill (C4E_CONST C4eElement *x, C4eArchDigit digit)
	Fills all digits of a set/field element with a constant.
C4eSysStatus	c4e_elem_rand (C4eElement *x)
	Fills all digits of a set/field element with random, with normalization.
void	c4e_elem_digits_shl (C4eElement *x, C4eArchIdx shift)
	Shift left of element digits with clear of least significant ones.
void	c4e_elem_bits_shl (C4eElement *x, C4eArchUint shift)
	Shift left of a set/field element by a number of bits, less than C4E_SYS_DIGIT_BITS.
void	c4e_elem_shl (C4eElement *x, C4eArchSize shift)
	Shift left of a set/field element by a number of bits.
void	c4e_elem_digits_shr (C4eElement *x, C4eArchIdx shift)
	Shift right of element digits, with size correction.
void	c4e_elem_bits_shr (C4eElement *x, C4eArchUint shift)
	Shift right of a set/field element by a number of bits, less than C4E_SYS_DIGIT_BITS.
void	c4e_elem_shr (C4eElement *x, C4eArchSize shift)
	Shift right of a set/field element by a number of bits.
void	c4e_elem_os2e (C4E_CONST C4eArchUint8 C4E_RESTRICT osp, C4eArchSize len, C4eElement C4E_RESTRICT elem)
	Octet string to element conversion primitive, according to IEEE Std 1363, section 5.5 and NIST SP800-56A, appendix C.
C4eArchSize	c4e_elem_e2os (C4E_CONST C4eElement C4E_RESTRICT elem, C4eArchSize bufsize, C4eArchUint8 C4E_RESTRICT buf)
	Element to octet string conversion primitive, according to IEEE Std 1363, section 5.5 and NIST SP800-56A, appendix C.

Detailed Description

Big Number declarations.

Author:: Copyright (C) 2007-2015 Ralf Hoppe <ralf.hoppe@ieee.org>

Version:

Id: c4e_elements.h 568 2015-05-17 14:32:36Z ralf

Definition in file c4e_elements.h.

Define Documentation

#define C4E_ELEM_ASGN_MEM	(	elem,
		digmem		)

Assign digits memory to an element.

Parameters:

`[in]`	elem	Pointer to element of type C4eElement, a big number or binary polynomial.
`[in]`	digmem	Digits memory (of type C4eArchDigit*) to be assigned to element `elem`.

See also:: C4eElement

Definition at line 119 of file c4e_elements.h.

#define C4E_ELEM_DIGITS_NUM ( bytes )

Calculation of equivalent number of digits (of type C4eArchDigit) from number of bytes.

Parameters:

[in] bytes Number of bytes.

Returns:: Equivalent number of digits as type C4eArchIdx.

Definition at line 133 of file c4e_elements.h.

#define C4E_ELEM_IS_ZERO ( x )

Checks whether an element is zero (or not).

Precondition:: The set/field element x must be normalized, for example using function c4e_elem_norm(). So if it's size is zero it's value is zero too.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or binary polynomial.

Returns:: C4E_TRUE if element is zero, else C4E_FALSE.

Definition at line 151 of file c4e_elements.h.

#define C4E_ELEM_IS_NZERO ( x )

Checks whether an element is NOT zero.

Precondition:: The set/field element x must be normalized, for example using function c4e_elem_norm(). So if it's size is zero it's value is zero too.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or binary polynomial.

Returns:: C4E_TRUE if element is NOT zero, else C4E_FALSE.

Definition at line 169 of file c4e_elements.h.

#define C4E_ELEM_SET_ZERO ( x )

Sets an element to zero.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or polynomial.

Definition at line 180 of file c4e_elements.h.

#define C4E_ELEM_IS_ONE ( x )

Checks whether an element is one.

Precondition:: The set/field element x must be normalized, for example using function c4e_elem_norm().

Parameters:

[in] x Pointer to element of type C4eElement, a big number or binary polynomial.

Returns:: C4E_TRUE if element is one, else C4E_FALSE.

Definition at line 196 of file c4e_elements.h.

#define C4E_ELEM_SET_ONE ( x )

Sets an element to one.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or polynomial.

Definition at line 207 of file c4e_elements.h.

#define C4E_ELEM_IS_EVEN ( elem )

Tests if an element is even.

Precondition:: Check elem with C4E_ELEM_IS_ZERO() to ensure it is not zero (before using this macro). If elem is zero, then the return value may be wrong.

Parameters:

[in] elem Pointer to a set/field element of type C4eElement (big number or polynomial).

Returns:: C4E_TRUE if element is even, else C4E_FALSE.

Definition at line 229 of file c4e_elements.h.

#define C4E_ELEM_IS_ODD ( elem )

Tests if an element is odd.

Precondition:: Check elem with C4E_ELEM_IS_ZERO() to ensure it is not zero (before using this macro). If elem is zero, then the return value may be wrong.

Parameters:

[in] elem Pointer to a set/field element of type C4eElement (big number or polynomial).

Returns:: C4E_TRUE if element is odd, else C4E_FALSE.

Definition at line 248 of file c4e_elements.h.

#define C4E_ELEM_IS_NORM ( x )

Tests if an element is normalized.

Parameters:

[in] x Pointer to a set/field element of type C4eElement (big number or polynomial).

Returns:: C4E_TRUE if element x is normalized, else C4E_FALSE.

Definition at line 261 of file c4e_elements.h.

#define C4E_ELEM_MUL2 ( x )

Multiplication of a set/field element by two.

Note:: Possibly increases x->size.; Multiplication by two is equivalent to shift left one bit.

Parameters:

[in,out] x Pointer to set/field element to be shifted left.

Definition at line 277 of file c4e_elements.h.

#define C4E_ELEM_DIV2 ( x )

Division of a set/field element by two.

Note:: Division by two is equivalent to shift right one bit.; Possibly decreases x->size.

Parameters:

[in,out] x Pointer to set/field element to be shifted right.

Definition at line 291 of file c4e_elements.h.

#define C4E_ELEM_ASSERT_IN ( x )

Assert an elements pointer, which is a input parameter.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or polynomial.

Definition at line 303 of file c4e_elements.h.

#define C4E_ELEM_ASSERT_PTR ( x )

Assert the pointer members of an elements structure.

Note:: This macro may be usual for output parameters checking.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or polynomial.

Definition at line 316 of file c4e_elements.h.

#define C4E_ELEM_ASSERT_NORM ( x )

Assert an element is normalized.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or polynomial.

Definition at line 329 of file c4e_elements.h.

#define C4E_ELEM_ASSERT_NZERO ( x )

Assert an element is none-zero.

Parameters:

[in] x Pointer to element of type C4eElement, a big number or polynomial.

Definition at line 341 of file c4e_elements.h.

Enumeration Type Documentation

enum C4eElemCmp

Elements (big numbers or binary polynomials) comparision result.

Enumerator:

C4eElemCmpEQ	Elements are equal
C4eElemCmpLT	First element is less than second
C4eElemCmpGT	First element is greater than second

Definition at line 58 of file c4e_elements.h.

Function Documentation

C4eArchDigit c4e_elem_msb ( C4E_CONST C4eElement * x )

Returns a (single) bit mask for the most significant bit (which is one, in most significant digit) of element x.

Precondition:: The element x must be normalized.

Parameters:

[in] x Pointer to a set/field element.

Returns:: A bit mask for the most significant bit (which is 1) in most significant digit (MSD) of element x. If all bits in MSD are zero (x is not normalized), then it returns zero.

C4eArchSize c4e_elem_bits ( C4E_CONST C4eElement * x )

This function returns the number of significant bits in an element.

Attention:: If x is zero (or not normalized) then c4e_elem_bits() simply returns zero. If this happen then you should check if x itself isn't zero, in case this is important for your algorithm.

Precondition:: The element x must be normalized, e.g. by using function c4e_elem_norm().

Parameters:

[in] x Pointer to set/field element.

Returns:: The number of used bits in element x.

void c4e_elem_norm ( C4eElement * x )

Normalization of a set/field element, means removal of leading zero digits.

Parameters:

[in,out] x Pointer to a set/field element, which has to be normalized.

void c4e_elem_cpy	(	C4E_CONST C4eElement *C4E_RESTRICT	src,
		C4eElement *C4E_RESTRICT	dst
	)

Copies a set/field element.

Parameters:

`[in]`	src	Pointer to source element.
`[out]`	dst	Pointer to destination, which must have set `dst->digits` pointing to allocated memory.

void c4e_elem_swap	(	C4eElement *C4E_RESTRICT	elem1,
		C4eElement *C4E_RESTRICT	elem2
	)

Swaps all digits of two set/field elements (and changes it's size).

Note:: Does not change the digit pointers elem1->digits and elem2->digits.

Parameters:

`[in,out]`	elem1	Pointer to first set/field element.
`[in,out]`	elem2	Pointer to second set/field element.

void c4e_elem_fill	(	C4E_CONST C4eElement *	x,
		C4eArchDigit	digit
	)

Fills all digits of a set/field element with a constant.

Note:: Parameter x can be declared as C4E_CONST because the structure it points to isn't modified. Instead only the digits in x->digits[] will change (and the double indirection prevents any const inheritance, at least when using "C").

Parameters:

`[in,out]`	x	Set/field element to fill.
`[in]`	digit	Pattern to fill into all digits.

See also:: C4eElement, C4E_ELEM_ASGN_MEM()

C4eSysStatus c4e_elem_rand ( C4eElement * x )

Fills all digits of a set/field element with random, with normalization.

Precondition:: The Random Number Generator (RNG) must be initialized at user side, then installed via function c4e_rng_install().

Parameters:

[in,out] x Set/field element to fill.

Returns:: On success returns C4E_STATUS_OK. All other return values shall be interpreted as an error.

See also:: C4eElement, C4E_ELEM_ASGN_MEM()

void c4e_elem_digits_shl	(	C4eElement *	x,
		C4eArchIdx	shift
	)

Shift left of element digits with clear of least significant ones.

Postcondition:: x->size increased by shift (except for the case that x is zero).

Parameters:

`[in,out]`	x	Set/field element to be shifted left.
`[in]`	shift	The number of digits `x` shall be shifted left.

void c4e_elem_bits_shl	(	C4eElement *	x,
		C4eArchUint	shift
	)

Shift left of a set/field element by a number of bits, less than C4E_SYS_DIGIT_BITS.

Note:: Possibly increases x->size.

Parameters:

`[in,out]`	x	Set/field element to be shifted left.
`[in]`	shift	The number of bits (0 ... C4E_SYS_DIGIT_BITS-1).

See also:: c4e_bvec_shl()

void c4e_elem_shl	(	C4eElement *	x,
		C4eArchSize	shift
	)

Shift left of a set/field element by a number of bits.

Note:: Possibly increases x->size.

Parameters:

`[in,out]`	x	Set/field element to be shifted left.
`[in]`	shift	The number of bits `x` shall be shifted left.

void c4e_elem_digits_shr	(	C4eElement *	x,
		C4eArchIdx	shift
	)

Shift right of element digits, with size correction.

Postcondition:: x->size decreased by shift, but at most to zero.

Parameters:

`[in,out]`	x	Set/field element to be shifted right.
`[in]`	shift	The number of digits `x` shall be shifted right.

void c4e_elem_bits_shr	(	C4eElement *	x,
		C4eArchUint	shift
	)

Shift right of a set/field element by a number of bits, less than C4E_SYS_DIGIT_BITS.

Note:: Possibly decreases x->size.

Parameters:

`[in,out]`	x	Set/field element to be shifted right.
`[in]`	shift	The number of bits (0 ... C4E_SYS_DIGIT_BITS-1).

See also:: c4e_mpvec_shr()

void c4e_elem_shr	(	C4eElement *	x,
		C4eArchSize	shift
	)

Shift right of a set/field element by a number of bits.

Note:: Possibly decreases x->size.

Parameters:

`[in,out]`	x	Set/field element to be shifted right.
`[in]`	shift	The number of bits `x` shall be shifted right.

c4e_elements.h File Reference

(Version 568)

Data Structures

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation