Header file for the Nanocrypto EC prime field management APIs. More...

Functions
MOC_EXTERN MSTATUS	PRIMEFIELD_add (PrimeFieldPtr pField, PFEPtr pSumAndValue, ConstPFEPtr pAddend)
	Adds prime field elements. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_add2 (PrimeFieldPtr pField, PFEPtr pSum, ConstPFEPtr pAddend, ConstPFEPtr pAddend2)
	Adds two prime field elements. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_addAux (PrimeFieldPtr pField, PFEPtr pSumAndValue, ConstPFEPtr pAddend, ConstPFEPtr pModulus)
	Performs an arbitrary modular addition. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_additiveInvert (PrimeFieldPtr pField, PFEPtr pA)
	Additively inverts a prime field element inplace. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_barrettMultiply (PrimeFieldPtr pField, PFEPtr pProduct, ConstPFEPtr pA, ConstPFEPtr pB, ConstPFEPtr pModulo, ConstPFEPtr pMu)
	Performs an arbitrary modular multiplication with the Barrett reduction routine. More...

MOC_EXTERN sbyte4	PRIMEFIELD_cmp (PrimeFieldPtr pField, ConstPFEPtr pA, ConstPFEPtr pB)
	Compares two prime field elements. More...

MOC_EXTERN sbyte4	PRIMEFIELD_cmpToUnsigned (PrimeFieldPtr pField, ConstPFEPtr pA, ubyte4 val)
	Compares a prime field element to an unsigned small integer. More...

MOC_EXTERN intBoolean	PRIMEFIELD_comparePrimeFields (PrimeFieldPtr pField1, PrimeFieldPtr pField2)

MOC_EXTERN MSTATUS	PRIMEFIELD_copyElement (PrimeFieldPtr pField, PFEPtr pDestElem, ConstPFEPtr pSrcElem)
	Copies a prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_deleteElement (PrimeFieldPtr pField, PFEPtr *ppDeleteElem)
	Deletes a prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_divide (PrimeFieldPtr pField, PFEPtr pResult, ConstPFEPtr pA, ConstPFEPtr pDivisor)
	Multipies a prime field element by the inverse of another element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_getAsByteString (PrimeFieldPtr pField, ConstPFEPtr pA, ubyte *b, sbyte4 len)
	Converts a prime field element to a Big Endian byte array. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_getAsByteString2 (PrimeFieldPtr pField, ConstPFEPtr pA, ConstPFEPtr pB, ubyte *b, sbyte4 len)
	Converts two prime field elements to Big Endian byte arrays concatenated. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_getBit (PrimeFieldPtr pField, ConstPFEPtr pA, ubyte4 bitNum, ubyte *bit)
	Gets a bit in a prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_getElementByteStringLen (PrimeFieldPtr pField, sbyte4 *len)
	Gets the length of an arbitrary prime field element when written as a byte array. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_getPrime (PrimeFieldPtr pField, vlong **ppPrime)
	Gets the prime number associateed with the prime field as a new vlong. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_inverse (PrimeFieldPtr pField, PFEPtr pInverse, ConstPFEPtr pA)
	Multiplicatively inverts a prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_inverseAux (sbyte4 k, PFEPtr pInverse, ConstPFEPtr pA, ConstPFEPtr pModulus)
	Performs an arbitrary modular inversion. More...

MOC_EXTERN intBoolean	PRIMEFIELD_match (PrimeFieldPtr pField, ConstPFEPtr pA, ConstPFEPtr pB)
	Tests equality for two prime field elements. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_multiply (PrimeFieldPtr pField, PFEPtr pProduct, ConstPFEPtr pA, ConstPFEPtr pB)
	Multiplies prime field elements. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_newElement (PrimeFieldPtr pField, PFEPtr *ppNewElem)
	Allocates a new prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_newElementFromMpint (const ubyte pBuffer, ubyte4 bufSize, ubyte4 pBufIndex, PrimeFieldPtr pField, PFEPtr *ppNewElem)
	Creates a new prime field element from a multiple precision integer. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_newElementFromVlong (PrimeFieldPtr pField, const vlong pV, PFEPtr ppNewElem)
	Creates a new prime field element from a vlong element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_newMpintFromElement (PrimeFieldPtr pField, ConstPFEPtr pElem, ubyte *ppNewMpint, sbyte4 pRetMpintLength, vlong **ppVlongQueue)
	Creates a new multiple precision integer from a prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_newVlongFromElement (PrimeFieldPtr pField, ConstPFEPtr pElem, vlong ppNewElem, vlong ppQueue)
	Creates a new vlong from a prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_setToByteString (PrimeFieldPtr pField, PFEPtr pA, const ubyte *b, sbyte4 len)
	Sets a prime field element from a Big Endian byte array. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_setToUnsigned (PrimeFieldPtr pField, PFEPtr pA, ubyte4 val)
	Sets a prime field element to an unsigned small integer. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_shiftR (PrimeFieldPtr pField, PFEPtr pA)
	Right bit shifts a prime field element a single bit. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_specialExp448 (PFEPtr pResult, ConstPFEPtr pA, byteBoolean isInverse)
	Special finite field exponentiation for inverses or square roots. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_squareRoot (PrimeFieldPtr pField, PFEPtr pResult, ConstPFEPtr pA)
	Computes the square root of a prime field element. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_subtract (PrimeFieldPtr pField, PFEPtr pResultAndValue, ConstPFEPtr pSubtract)
	Subtracts prime field elements. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_subtract2 (PrimeFieldPtr pField, PFEPtr pResult, ConstPFEPtr pMinuend, ConstPFEPtr pSubtrahend)
	Subtracts two prime field elements. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_writeByteString (PrimeFieldPtr pField, ConstPFEPtr pA, ubyte *b, sbyte4 len)
	Writes a prime field element to an existing byte array. More...

MOC_EXTERN MSTATUS	PRIMEFIELD_xor (PrimeFieldPtr pField, PFEPtr pResultAndValue, ConstPFEPtr pXor)
	Xor's prime field elements. More...

Variables
MOC_EXTERN_PRIMEFLD_H const PrimeFieldPtr	PF_p192

MOC_EXTERN_PRIMEFLD_H const PrimeFieldPtr	PF_p224

MOC_EXTERN_PRIMEFLD_H const PrimeFieldPtr	PF_p256

MOC_EXTERN_PRIMEFLD_H const PrimeFieldPtr	PF_p384

MOC_EXTERN_PRIMEFLD_H const PrimeFieldPtr	PF_p448

MOC_EXTERN_PRIMEFLD_H const PrimeFieldPtr	PF_p521

Detailed Description

This file documents the definitions, enumerations, structures, and functions of the NanoCrypto EC prime field management APIs.

To enable the functions in primeec.{c,h}, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_ECC__

primefld.h

Function Documentation

◆ PRIMEFIELD_add()

MOC_EXTERN MSTATUS PRIMEFIELD_add	(	PrimeFieldPtr	pField,
		PFEPtr	pSumAndValue,
		ConstPFEPtr	pAddend
	)

Adds prime field elements inplace with respect to the first input. The result is a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pSumAndValue	The first addend, which will be replaced with the resulting sum.
pAddend	The second addend. It is ok for this to be the same pointer as pSumAndValue.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_add2()

MOC_EXTERN MSTATUS PRIMEFIELD_add2	(	PrimeFieldPtr	pField,
		PFEPtr	pSum,
		ConstPFEPtr	pAddend,
		ConstPFEPtr	pAddend2
	)

Adds two prime field elements with a distinc pointer for the result. The result is a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pSum	The resulting sum. This must be distinct pointer from pAddend2.
pAddend	The first addend. It is ok for this to be the same pointer as pSum.
pAddend2	The second addend. It is ok for this to be the same pointer as pAddend but must be distinct from pSum.

Must enable one of the curve448 algorithms in order to use this method.

             + \c \__ENABLE_MOCANA_ECC_EDDSA_448__
             + \c \__ENABLE_MOCANA_ECC_EDDH_448__

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_addAux()

MOC_EXTERN MSTATUS PRIMEFIELD_addAux	(	PrimeFieldPtr	pField,
		PFEPtr	pSumAndValue,
		ConstPFEPtr	pAddend,
		ConstPFEPtr	pModulus
	)

Performs an arbitrary modular addition. This routine acts on two prime field elements but will reduce their (big integer) sum by an arbitrary modulus. The result should no longer be considered a prime field element even though it is stored in such.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pSumAndValue	The first addend, which will be replaced with the resulting sum.
pAddend	The second addend. It is ok for this to be the same pointer as pSumAndValue.
pModulo	The modulus for which to reduce the product by. This should not be p.

Warning: For an arbitary modulus the resulting pSumAndValue will not necessarily be a reduced mod p prime field element.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_additiveInvert()

MOC_EXTERN MSTATUS PRIMEFIELD_additiveInvert	(	PrimeFieldPtr	pField,
		PFEPtr	pA
	)

Additively inverts a prime field element inplace. The result is a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The element to be additively inverted and the result of the inversion.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_barrettMultiply()

MOC_EXTERN MSTATUS PRIMEFIELD_barrettMultiply	(	PrimeFieldPtr	pField,
		PFEPtr	pProduct,
		ConstPFEPtr	pA,
		ConstPFEPtr	pB,
		ConstPFEPtr	pModulo,
		ConstPFEPtr	pMu
	)

Performs an arbitrary modular multiplication with the Barrett reduction routine. This routine acts on two prime field elements but will reduce their (big integer) product by an arbitrary modulus. The result should no longer be considered a prime field element even though it is stored in such.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pProduct	The resulting product modulo the pModulo passed in.
pA	The first input element.
pB	The second input element.
pModulo	The modulus for which to reduce the product by. This should not be p.
pMu	The Barrett multiplication constant associated with the pModulo passed in.

Warning: For an arbitary modulus the resulting pProduct will not necessarily be a reduced mod p prime field element.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_cmp()

MOC_EXTERN sbyte4 PRIMEFIELD_cmp	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pA,
		ConstPFEPtr	pB
	)

Compares two prime field elements (considered as integers).

Parameters

pField	The globally defined prime field pointer associated with the elements.
pA	The first element to be compared.
pB	The second element to be compared.

Returns: One (1) if pA > pB, zero (0) if pA and pB are the same, and minus one (-1) if pA < pB.

◆ PRIMEFIELD_cmpToUnsigned()

MOC_EXTERN sbyte4 PRIMEFIELD_cmpToUnsigned	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pA,
		ubyte4	val
	)

Compares a prime field element to an unsigned small integer.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The first element to be compared.
val	The small 4 byte unsigned integer to be compared.

Returns: One (1) if pA > val, zero (0) if pA and val are the same, and minus one (-1) if pA < val.

◆ PRIMEFIELD_copyElement()

MOC_EXTERN MSTATUS PRIMEFIELD_copyElement	(	PrimeFieldPtr	pField,
		PFEPtr	pDestElem,
		ConstPFEPtr	pSrcElem
	)

Copies a finite field element to a previously allocated element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pDestElem	The destination element of the copy. This must have been previously allocated.
pSrcElem	The source element of the copy.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_deleteElement()

MOC_EXTERN MSTATUS PRIMEFIELD_deleteElement	(	PrimeFieldPtr	pField,
		PFEPtr *	ppDeleteElem
	)

Zeroes and frees memory allocaeted within a prime field element.

Parameters

pField	The globally defined prime field pointer associated with the element.
ppDeleteElem	Pointer to the location that holds the element to be deleted.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_divide()

MOC_EXTERN MSTATUS PRIMEFIELD_divide	(	PrimeFieldPtr	pField,
		PFEPtr	pResult,
		ConstPFEPtr	pA,
		ConstPFEPtr	pDivisor
	)

Multipies a prime field element by the inverse of another element. If the divisor element is zero an error code will be returned. The result will be a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pResult	The resulting element. It is ok for this to be the same pointer as pA or pDivisor.
pA	The first input element to be multipied.
PDivisor	The second input element that will be inverted and multiplied. It is ok for this to be the same pointer as pA.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_getAsByteString()

MOC_EXTERN MSTATUS PRIMEFIELD_getAsByteString	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pA,
		ubyte **	b,
		sbyte4 *	len
	)

Converts a prime field element to a Big Endian byte array. Leading zeros will be preserved, ie the length of the byte array will depend only on the field and not on the value of the element. The resulting array will be in a newly allocated buffer. Be sure to FREE it when done with it.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The input element.
b	Pointer to the newly allocated buffer that will hold the Big Endian byte array.
len	Contents will be set to the length of the buffer b in bytes. This only depends on the field and not the value of the element.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_getAsByteString2()

MOC_EXTERN MSTATUS PRIMEFIELD_getAsByteString2	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pA,
		ConstPFEPtr	pB,
		ubyte **	b,
		sbyte4 *	len
	)

Converts two prime field elements to Big Endian byte arrays concatenated. Leading zeros will be preserved, ie the length of the byte array will depend only on the field and not on the value of the elements. The resulting array will be in a newly allocated buffer. Be sure to FREE it when done with it.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pA	The first input element.
pB	The second input element.
b	Pointer to the newly allocated buffer that will hold the Big Endian byte arrays.
len	Contents will be set to the length of the buffer b in bytes. This only depends on the field and not the value of the elements.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_getBit()

MOC_EXTERN MSTATUS PRIMEFIELD_getBit	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pA,
		ubyte4	bitNum,
		ubyte *	bit
	)

Gets a bit in a prime field element. The 0-th bit is considered the least significant.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The input element.
bitNum	The bit to find, beginning with 0 being the least signficant.
bit	Contents will be set to the element's bitNum bit, ie to 0 or 1.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_getElementByteStringLen()

MOC_EXTERN MSTATUS PRIMEFIELD_getElementByteStringLen	(	PrimeFieldPtr	pField,
		sbyte4 *	len
	)

Gets the length of an arbitrary prime field element when written as a byte array.

Parameters

pField	Prime field pointer to the field in question.
len	Contents will be set to the length in bytes of an element when written in byte array form.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_getPrime()

MOC_EXTERN MSTATUS PRIMEFIELD_getPrime	(	PrimeFieldPtr	pField,
		vlong **	ppPrime
	)

Gets the prime number associateed with the prime field as a newly allocated vlong. Be sure to call VLONG_freeVlong to free allocated memory when done with the new vlong.

Parameters

pField	The input prime field.
ppPrime	Pointer that will be set to the location of the newly created vlong element representing the prime p associated with the field.

Must define + __ENABLE_MOCANA_VLONG_ECC_CONVERSION__ in order to use this method.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_inverse()

MOC_EXTERN MSTATUS PRIMEFIELD_inverse	(	PrimeFieldPtr	pField,
		PFEPtr	pInverse,
		ConstPFEPtr	pA
	)

Multiplicatively inverts a prime field element. If the input element is zero an error code will be returned. The result will be a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pInverse	The resulting inverse element. It is ok for this to be the same pointer as pA.
pA	The input element to be inverted.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_inverseAux()

MOC_EXTERN MSTATUS PRIMEFIELD_inverseAux	(	sbyte4	k,
		PFEPtr	pInverse,
		ConstPFEPtr	pA,
		ConstPFEPtr	pModulus
	)

Performs an arbitrary modular inversion. This routine acts on a prime field element but will invert it (as a big integer) by an arbitrary modulus. The modulus need not be prime. The result should no longer be considered a prime field element even though it is stored in such. An error will be returned if the input element is not invertible.

Parameters

k	The number of words in pModulus. pA cannot be a larger size in words.
pInverse	The resulting inverse modulo pModulus.
pA	The input element to be inverted.
pModulus	The input modulus.

Warning: For an arbitary modulus the resulting pInverse will not necessarily be a reduced mod p prime field element.

Returns: OK (0) if successful and an inverse exists, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_match()

MOC_EXTERN intBoolean PRIMEFIELD_match	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pA,
		ConstPFEPtr	pB
	)

Tests equality for two prime field elements.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pA	The first input element.
pB	The second input element.

Returns: TRUE if pA and pB represent the same element, FALSE otherwise.

◆ PRIMEFIELD_multiply()

MOC_EXTERN MSTATUS PRIMEFIELD_multiply	(	PrimeFieldPtr	pField,
		PFEPtr	pProduct,
		ConstPFEPtr	pA,
		ConstPFEPtr	pB
	)

Multiplies prime field elements. The result is a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pProduct	The resulting product. It is ok for this to be the same pointer as pA or pB.
pA	The first input.
PB	The second input. It is ok for this to be the same pointer as pA.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_newElement()

MOC_EXTERN MSTATUS PRIMEFIELD_newElement	(	PrimeFieldPtr	pField,
		PFEPtr *	ppNewElem
	)

Allocates a new prime field element. Be sure to call PRIMEFIELD_deleteElement when done in order to free the allocated memory.

Parameters

pField	One of the globally defined prime field pointers. PF_p192 (if enabled) PF_p224 PF_p256 PF_p384 PF_p448 (if enabled) PF_p521
ppNewElem	Pointer to the location that will receive the new element.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_newElementFromMpint()

MOC_EXTERN MSTATUS PRIMEFIELD_newElementFromMpint	(	const ubyte *	pBuffer,
		ubyte4	bufSize,
		ubyte4 *	pBufIndex,
		PrimeFieldPtr	pField,
		PFEPtr *	ppNewElem
	)

Creates a new prime field element from a multiple precision integer. The new element will be allocates so be sure to call PRIMEFIELD_deleteElement when finished with it. The input integer can be contained in a buffer of more than one integer and a pointer to the next integer will be updated upon successful completion of this method.

Parameters

pBuffer	Buffer holding the multiple precision integer(s) to be copied and converted.
bufSize	The length of pBuffer in bytes.
pBufIndex	Offset in pBuffer where the current integer to be converted is stored. The contents of this pointer will be updated to the next potential integer in the buffer upon succesful completion of this method.
pField	The globally defined prime field pointer you wish to associate with the element.
ppNewElem	Pointer to the location that will hold the newly allocated prime field element.

Must define + __ENABLE_MOCANA_VLONG_ECC_CONVERSION__ in order to use this method.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_newElementFromVlong()

MOC_EXTERN MSTATUS PRIMEFIELD_newElementFromVlong	(	PrimeFieldPtr	pField,
		const vlong *	pV,
		PFEPtr *	ppNewElem
	)

Allocates and creates a new prime field element from a vlong element. Be sure to call PRIMEFIELD_deleteElement to free allocated memory when done with the new element.

Parameters

pField	The globally defined prime field pointer you wish to associate with the element.
pV	Pointer to the vlong element to be copied and converted.
ppNewElem	Pointer that will be set to the location of the newly created prime field element.

Must define + __ENABLE_MOCANA_VLONG_ECC_CONVERSION__ in order to use this method.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_newMpintFromElement()

MOC_EXTERN MSTATUS PRIMEFIELD_newMpintFromElement	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pElem,
		ubyte **	ppNewMpint,
		sbyte4 *	pRetMpintLength,
		vlong **	ppVlongQueue
	)

Creates a new multiple precision integer from a prime field element. A buffer will be allocated to store the new integer. Be sure to FREE this buffer when done with it.

Parameters

pField	The globally defined prime field pointer associated with the element.
pElem	The input element to be copied and converted.
ppNewMpint	Pointer to the location that will hold the newly allocated multiple precision integer.
pRetMpintLength	Contents will be set to the number of bytes in the new integer.
ppVlongQueue	Pointer to an optional vlong queue.

Must define + __ENABLE_MOCANA_VLONG_ECC_CONVERSION__ in order to use this method.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_newVlongFromElement()

MOC_EXTERN MSTATUS PRIMEFIELD_newVlongFromElement	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pElem,
		vlong **	ppNewElem,
		vlong **	ppQueue
	)

Allocates and creates a new vlong from a prime field element. Be sure to call VLONG_freeVlong to free allocated memory when done with the new vlong.

Parameters

pField	The globally defined prime field pointer associated with the element.
pElem	The input element to be copied and converted.
ppNewElem	Pointer that will be set to the location of the newly created vlong.
ppQueue	Pointer to an optional vlong queue.

Must define + __ENABLE_MOCANA_VLONG_ECC_CONVERSION__ in order to use this method.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_setToByteString()

MOC_EXTERN MSTATUS PRIMEFIELD_setToByteString	(	PrimeFieldPtr	pField,
		PFEPtr	pA,
		const ubyte *	b,
		sbyte4	len
	)

Sets a prime field element from a Big Endian byte array. The integer represented must already be reduced, ie < p, else an error will be returned.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The target element to be set.
b	Buffer holding the input Big Endian byte array.
len	The length of the byte array b in bytes.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_setToUnsigned()

MOC_EXTERN MSTATUS PRIMEFIELD_setToUnsigned	(	PrimeFieldPtr	pField,
		PFEPtr	pA,
		ubyte4	val
	)

Sets a prime field element to an unsigned small integer.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The target element to be set.
val	The input small 4 byte unsigned integer.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_shiftR()

MOC_EXTERN MSTATUS PRIMEFIELD_shiftR	(	PrimeFieldPtr	pField,
		PFEPtr	pA
	)

Right bit shifts a prime field element a single bit. This operation is inplace. It is NOT a mod p divide by 2 operation.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The input which will be replaced with the resulting element.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_specialExp448()

MOC_EXTERN MSTATUS PRIMEFIELD_specialExp448	(	PFEPtr	pResult,
		ConstPFEPtr	pA,
		byteBoolean	isInverse
	)

Special finite field exponentiation method that can be used to compute the inverse of an element or a partial result needed for a square root computation. This is for the PF_p448 field only. The result is a standard mod p reduced element.

Parameters

pResult	The resulting element. It is ok for this to be the same pointer as pA.
pA	The input element to be exponentiated.
isInverse	If TRUE then pA^-1 = pA^(p-2) is calculated. If FALSE then pA^((p-3)/4) is calculated.

Must enable one of the curve448 algorithms in order to use this method.

              + \c \__ENABLE_MOCANA_ECC_EDDSA_448__
              + \c \__ENABLE_MOCANA_ECC_EDDH_448__

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_squareRoot()

MOC_EXTERN MSTATUS PRIMEFIELD_squareRoot	(	PrimeFieldPtr	pField,
		PFEPtr	pResult,
		ConstPFEPtr	pA
	)

Computes the square root of a prime field element or returns an error code if no such square root exists. The result if found will be a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pResult	The resulting square root of the input if it exists.
pA	The input element.

Warning: Be sure to always check for a return code of OK before proceeding, as (p+1)/2, of the finite field elements do not have square roots.

Returns: OK (0) for successful computation of a sqaure root, and ERR_NOT_FOUND (-6009) if no square root exists, or another negative error code upon computation failure.

◆ PRIMEFIELD_subtract()

MOC_EXTERN MSTATUS PRIMEFIELD_subtract	(	PrimeFieldPtr	pField,
		PFEPtr	pResultAndValue,
		ConstPFEPtr	pSubtract
	)

Subtracts prime field elements inplace with respect to the first input. The result is a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pResultAndValue	The minuend, which will be replaced with the resulting difference.
pAddend	The subtrahend. It is ok for this to be the same pointer as pResultAndValue.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_subtract2()

MOC_EXTERN MSTATUS PRIMEFIELD_subtract2	(	PrimeFieldPtr	pField,
		PFEPtr	pResult,
		ConstPFEPtr	pMinuend,
		ConstPFEPtr	pSubtrahend
	)

Subtracts two prime field elements with a distinc pointer for the result. The result is a standard mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pResult	The resulting difference. This must be distinct pointer from pSubtrahend.
pMinuend	The minuend. It is ok for this to be the same pointer as pResult.
pSubtrahend	The pSubtrahend. It is ok for this to be the same pointer as pMinuend but must be distinct from pResult.

Must enable one of the curve448 algorithms in order to use this method.

              + \c \__ENABLE_MOCANA_ECC_EDDSA_448__
              + \c \__ENABLE_MOCANA_ECC_EDDH_448__

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_writeByteString()

MOC_EXTERN MSTATUS PRIMEFIELD_writeByteString	(	PrimeFieldPtr	pField,
		ConstPFEPtr	pA,
		ubyte *	b,
		sbyte4	len
	)

Writes a prime field element to a previously existing array, in Big Endian form. Leading zeros will be preserved and the array must be big enough for arbitrary elements.

Parameters

pField	The globally defined prime field pointer associated with the element.
pA	The input element.
b	The buffer that will be filled with the Big Endian byte array.
len	The length of the buffer b in bytes.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

◆ PRIMEFIELD_xor()

MOC_EXTERN MSTATUS PRIMEFIELD_xor	(	PrimeFieldPtr	pField,
		PFEPtr	pResultAndValue,
		ConstPFEPtr	pXor
	)

Xor's prime field elements. The result is NOT necessarily a mod p reduced element.

Parameters

pField	The globally defined prime field pointer associated with the elements.
pResultAndValue	The first input element, which will be replaced with the resulting xor.
pXor	The second input element. It is ok for this to be the same pointer as pResultAndValue.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h

Functions

Variables

Detailed Description

Function Documentation

◆ PRIMEFIELD_add()

◆ PRIMEFIELD_add2()

◆ PRIMEFIELD_addAux()

◆ PRIMEFIELD_additiveInvert()

◆ PRIMEFIELD_barrettMultiply()

◆ PRIMEFIELD_cmp()

◆ PRIMEFIELD_cmpToUnsigned()

◆ PRIMEFIELD_copyElement()

◆ PRIMEFIELD_deleteElement()

◆ PRIMEFIELD_divide()

◆ PRIMEFIELD_getAsByteString()

◆ PRIMEFIELD_getAsByteString2()

◆ PRIMEFIELD_getBit()

◆ PRIMEFIELD_getElementByteStringLen()

◆ PRIMEFIELD_getPrime()

◆ PRIMEFIELD_inverse()

◆ PRIMEFIELD_inverseAux()

◆ PRIMEFIELD_match()

◆ PRIMEFIELD_multiply()

◆ PRIMEFIELD_newElement()

◆ PRIMEFIELD_newElementFromMpint()

◆ PRIMEFIELD_newElementFromVlong()

◆ PRIMEFIELD_newMpintFromElement()

◆ PRIMEFIELD_newVlongFromElement()

◆ PRIMEFIELD_setToByteString()

◆ PRIMEFIELD_setToUnsigned()

◆ PRIMEFIELD_shiftR()

◆ PRIMEFIELD_specialExp448()

◆ PRIMEFIELD_squareRoot()

◆ PRIMEFIELD_subtract()

◆ PRIMEFIELD_subtract2()

◆ PRIMEFIELD_writeByteString()

◆ PRIMEFIELD_xor()