Header file for the Nanocrypto Finite Field Elliptic Curve API. More...

Typedefs
typedef struct MEccKeyTemplate *	MEccKeyTemplatePtr

Functions
MOC_EXTERN MSTATUS	EC_addMultiplyPoint (PrimeFieldPtr pPF, PFEPtr pResX, PFEPtr pResY, ConstPFEPtr pAddedX, ConstPFEPtr pAddedY, ConstPFEPtr k, ConstPFEPtr pX, ConstPFEPtr pY)
	Computes a scalar-point multiplication plus an addition on a prime curve. More...

MOC_EXTERN MSTATUS	EC_byteStringToPoint (PEllipticCurvePtr pEC, const ubyte s, sbyte4 len, PFEPtr ppX, PFEPtr *ppY)
	Converts an uncompressed form point to newly allocated prime field elements. More...

MOC_EXTERN MSTATUS	EC_cloneKey (ECCKey *ppNew, const ECCKey pSrc)
	Clones an ECCKey instance. More...

MOC_EXTERN MSTATUS	EC_combSize (PrimeFieldPtr pPF, sbyte4 windowSize, sbyte4 *size)
	Computes the total number of `pf_units` that will be needed to store a comb. More...

MOC_EXTERN intBoolean	EC_compareEllipticCurves (PEllipticCurvePtr pEC1, PEllipticCurvePtr pEC2)
	Compares if two elliptic curve pointers are the same curve. More...

MOC_EXTERN MSTATUS	EC_computeYFromX (PEllipticCurvePtr pEC, ConstPFEPtr x, PFEPtr y)
	Computes a Y coordinate of a point on the curve from an X coordinate. More...

MOC_EXTERN MSTATUS	EC_createPrimeCurveMutexes (void)
	Creates globally stored mutexes used for thread safety. More...

MOC_EXTERN MSTATUS	EC_deleteComb (PrimeFieldPtr pPF, sbyte4 windowSize, PFEPtr *pComb)
	Zeros and frees a comb. More...

MOC_EXTERN MSTATUS	EC_deleteKey (ECCKey **ppKey)
	Deletes an ECCKey instance. More...

MOC_EXTERN MSTATUS	EC_deletePrimeCurveCombsAndMutexes (void)
	Zeros and frees globally stored combs and mutexes. More...

MOC_EXTERN MSTATUS	EC_equalKey (const ECCKey pKey1, const ECCKey pKey2, byteBoolean *res)
	Tests whether two ECCKeys have identical public keys. More...

MOC_EXTERN MSTATUS	EC_generateKeyPair (PEllipticCurvePtr pEC, RNGFun rngFun, void *rngArg, PFEPtr k, PFEPtr pQx, PFEPtr pQy)
	Generates a new ECC private/public key pair. More...

MOC_EXTERN MSTATUS	EC_getPointByteStringLen (PEllipticCurvePtr pEC, sbyte4 *pLen)
	Gets the length in bytes of an arbitrary point's uncompressed form. More...

MOC_EXTERN PrimeFieldPtr	EC_getUnderlyingField (PEllipticCurvePtr pEC)
	Gets the underlying prime field associated with a prime curve. More...

MOC_EXTERN MSTATUS	EC_multiplyPoint (PrimeFieldPtr pPF, PFEPtr pResX, PFEPtr pResY, ConstPFEPtr k, ConstPFEPtr pX, ConstPFEPtr pY)
	Computes a scalar-point multiplication on a prime curve. More...

MOC_EXTERN MSTATUS	EC_newKey (PEllipticCurvePtr pEC, ECCKey **ppNewKey)
	Allocates a new ECCKey instance. More...

MOC_EXTERN MSTATUS	EC_pointToByteString (PEllipticCurvePtr pEC, ConstPFEPtr pX, ConstPFEPtr pY, ubyte *s, sbyte4 pLen)
	Converts a point on the curve to an uncompressed form byte array. More...

MOC_EXTERN MSTATUS	EC_precomputeComb (PrimeFieldPtr pPF, ConstPFEPtr pQx, ConstPFEPtr pQy, sbyte4 windowSize, PFEPtr *pPrecomputed)
	Computes the comb of a point on the curve. More...

MOC_EXTERN MSTATUS	EC_precomputeCombOfCurve (PEllipticCurvePtr pEC, sbyte4 windowSize, PFEPtr *pCurvePrecomputed)
	Computes the comb of the curve's large cyclic group generator. More...

MOC_EXTERN MSTATUS	EC_setKeyParameters (ECCKey pKey, const ubyte point, ubyte4 pointLen, const ubyte *scalar, ubyte4 scalarLen)
	Sets the key parameters of an ECCKey. More...

MOC_EXTERN MSTATUS	EC_setPointToByteString (PEllipticCurvePtr pEC, const ubyte *s, sbyte4 len, PFEPtr pX, PFEPtr pY)
	Converts an uncompressed form point to prime field elements. More...

MOC_EXTERN MSTATUS	EC_setPrivateKey (ECCKey pKey, ubyte pScalar, ubyte4 scalarLen)
	Sets the private key parameter of an ECCKey. More...

MOC_EXTERN MSTATUS	EC_verifyKeyPair (PEllipticCurvePtr pEC, ConstPFEPtr k, ConstPFEPtr pQx, ConstPFEPtr pQy)
	Verifies that a given private key is associated with a given public key. More...

MOC_EXTERN MSTATUS	EC_verifyPoint (PEllipticCurvePtr pEC, ConstPFEPtr pQx, ConstPFEPtr pQy)
	Verifies that a point is a valid point on the curve. More...

MOC_EXTERN MSTATUS	EC_verifyPublicKey (PEllipticCurvePtr pEC, ConstPFEPtr pQx, ConstPFEPtr pQy)
	Verifies that a public key point is a valid point on the curve. More...

MOC_EXTERN MSTATUS	EC_writePointToBuffer (PEllipticCurvePtr pEC, ConstPFEPtr pX, ConstPFEPtr pY, ubyte *s, sbyte4 len)
	Converts a point on the curve to an uncompressed form byte array. More...

MOC_EXTERN MSTATUS	ECDH_generateSharedSecret (PEllipticCurvePtr pEC, const ubyte pointByteString, sbyte4 pointByteStringLen, ConstPFEPtr scalarMultiplier, ubyte sharedSecret, sbyte4 sharedSecretLen)
	Generates a Diffie-Hellman shared secret from an uncompressed form public key. More...

MOC_EXTERN MSTATUS	ECDH_generateSharedSecretAux (PEllipticCurvePtr pEC, ConstPFEPtr pX, ConstPFEPtr pY, ConstPFEPtr scalarMultiplier, ubyte *sharedSecret, sbyte4 sharedSecretLen, sbyte4 flag)
	Generates a Diffie-Hellman shared secret. More...

MOC_EXTERN MSTATUS	ECDH_keyAgreementSchemePrimeCurve (ubyte4 mode, ECCKey pStatic, ECCKey pEphemeral, ubyte pOtherPartysStatic, ubyte4 otherStaticLen, ubyte pOtherPartysEphemeral, ubyte4 otherEphemeralLen, ubyte *ppSharedSecret, ubyte4 pSharedSecretLen)
	Generates a Diffie-Hellman shared secret via one of the major modes. More...

MOC_EXTERN MSTATUS	ECDSA_signDigestAux (PEllipticCurvePtr pEC, ConstPFEPtr d, RNGFun rngFun, void rngArg, const ubyte hash, ubyte4 hashLen, PFEPtr r, PFEPtr s)
	Signs a message digest via the ECDSA signature algorithm. More...

MOC_EXTERN MSTATUS	ECDSA_verifySignature (PEllipticCurvePtr pEC, ConstPFEPtr pPublicKeyX, ConstPFEPtr pPublicKeyY, const ubyte *hash, ubyte4 hashLen, ConstPFEPtr r, ConstPFEPtr s)
	Verifies a message digest via the ECDSA signature algorithm. More...

MOC_EXTERN MSTATUS	ECDSA_verifySignatureEx (PEllipticCurvePtr pEC, ConstPFEPtr pPublicKeyX, ConstPFEPtr pPublicKeyY, const ubyte *hash, ubyte4 hashLen, sbyte4 curveWinSize, ConstPFEPtr pCurvePrecomp, sbyte4 pubKeyWinSize, ConstPFEPtr pPubKeyPrecomp, ConstPFEPtr r, ConstPFEPtr s)
	Verifies a message digest via the ECDSA signature algorithm using provided combs. More...

Variables
MOC_EXTERN_PRIMEEC_H const PEllipticCurvePtr	EC_P192

MOC_EXTERN_PRIMEEC_H const PEllipticCurvePtr	EC_P224

MOC_EXTERN_PRIMEEC_H const PEllipticCurvePtr	EC_P256

MOC_EXTERN_PRIMEEC_H const PEllipticCurvePtr	EC_P384

MOC_EXTERN_PRIMEEC_H const PEllipticCurvePtr	EC_P521

Detailed Description

This file documents the definitions, enumerations, structures, and functions of the NanoCrypto Finite Field Elliptic Curve (EC) API.

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

__ENABLE_MOCANA_ECC__

primeec.h

Function Documentation

◆ EC_addMultiplyPoint()

MOC_EXTERN MSTATUS EC_addMultiplyPoint	(	PrimeFieldPtr	pPF,
		PFEPtr	pResX,
		PFEPtr	pResY,
		ConstPFEPtr	pAddedX,
		ConstPFEPtr	pAddedY,
		ConstPFEPtr	k,
		ConstPFEPtr	pX,
		ConstPFEPtr	pY
	)

Computes a scalar-point multiplication plus an addition on a prime curve. This is essentially (pResX, pResY) = k * (pX, pY) + (pAddedX, pAddedY). It is not checked that the input points are valid points on the curve.

Parameters

pPF	The globally defined prime field associated with the prime curve.
pResX	The resulting point's X coordinate.
pResY	The resulting point's Y coordinate.
pAddedX	The addended point's X coordinate.
pAddedY	The addended point's Y coordinate.
k	The input scalar stored in the form of a prime field element. This need not be a reduced prime field element.
pX	The to be scaled point's X coordinate.
pY	The to be scaled point's Y coordinate.

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

◆ EC_byteStringToPoint()

MOC_EXTERN MSTATUS EC_byteStringToPoint	(	PEllipticCurvePtr	pEC,
		const ubyte *	s,
		sbyte4	len,
		PFEPtr *	ppX,
		PFEPtr *	ppY
	)

Converts a byte array form uncompressed point to the point in the form of two newly allocated prime field elements. Be sure to free these elements when done with them by calling PRIMEFIELD_deleteElement on each.

Parameters

pEC	Pointer to the globally defined prime curve in question.
s	Buffer holding the uncompressed form point. This should begin with an 0x04 byte followed by X and Y in Big Endian each properly padded to the prime field's element length.
len	The length of the buffer s in bytes.
ppX	Pointer to the location that will hold the resulting X coordinate as a prime field element.
ppY	Pointer to the location that will hold the resulting Y coordinate as a prime field element.

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

◆ EC_cloneKey()

MOC_EXTERN MSTATUS EC_cloneKey	(	ECCKey **	ppNew,
		const ECCKey *	pSrc
	)

Allocates a new copy of an already existing ECCKey. Be sure to free this key when done with it by calling EC_deleteKey.

Parameters

ppNew	Pointer to the location that will receive the new key.
pSrc	Pointer to the previously existing key that will be cloned.

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

◆ EC_combSize()

MOC_EXTERN MSTATUS EC_combSize	(	PrimeFieldPtr	pPF,
		sbyte4	windowSize,
		sbyte4 *	size
	)

Computes the total number of pf_units that will be needed to store a comb with a given window size w. This is 2 * (2^w - 2) * n where n is the number of pf_units in a prime field element.

Parameters

pPF	The globally defined prime field associated to the curve in question.
windowSize	The input window size. This must be 2 or larger.
size	Contents will be set to the comb size.

To use this method one must define ENABLE_MOCANA_ECC_COMB and have ENABLE_MOCANA_SMALL_CODE_FOOTPRINT not defined.

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

◆ EC_compareEllipticCurves()

MOC_EXTERN intBoolean EC_compareEllipticCurves	(	PEllipticCurvePtr	pEC1,
		PEllipticCurvePtr	pEC2
	)

Compares if two elliptic curve pointers are the same curve.

Parameters

pEC1	Pointer to the first curve.
pEC2	Pointer to the second curve.

Returns: TRUE if the the two curves are the same, FALSE otherwise.

◆ EC_computeYFromX()

MOC_EXTERN MSTATUS EC_computeYFromX	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	x,
		PFEPtr	y
	)

Computes a Y coordinate of a point on the curve from an X coordinate. It will compute one of the two possible Y coordinates if it exists. If no such point (X,Y) exists then ERR_NOT_FOUND (-6009) is returned.

Parameters

pEC	Pointer to the globally defined prime curve in question.
x	The input X coordinate.
y	The resulting Y coordinate.

Returns: OK (0) if successful and such an (X,Y) exists. If no such (X,Y) exists then ERR_NOT_FOUND (-6009) is returned.

◆ EC_createPrimeCurveMutexes()

MOC_EXTERN MSTATUS EC_createPrimeCurveMutexes ( void )

Creates globally stored mutexes used for thread safety among comb generation for each of the prime curve's cyclic group generators. This method should only be called once and in an initialization phase, for example from CRYPTO_MOC_init. Be sure to then also call EC_deletePrimeCurveCombsAndMutexes in an appropriate cleanup phase.

To use this method one must define ENABLE_MOCANA_SIGNED_ODD_COMB_PERSIST and not have DISABLE_MOCANA_SIGNED_ODD_COMB not defined.

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

◆ EC_deleteComb()

MOC_EXTERN MSTATUS EC_deleteComb	(	PrimeFieldPtr	pPF,
		sbyte4	windowSize,
		PFEPtr *	pComb
	)

Zeros and frees a comb allocated by the EC_precomputeCombOfCurve or EC_precomputeComb methods.

Parameters

pPF	The globally defined prime field associated to the curve in question.
windowSize	The input comb's window size. This MUST match the window size used when the comb was created.
pComb	Pointer to the location of the comb to be deleted.

To use this method one must define ENABLE_MOCANA_ECC_COMB and have ENABLE_MOCANA_SMALL_CODE_FOOTPRINT not defined.

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

◆ EC_deleteKey()

MOC_EXTERN MSTATUS EC_deleteKey ( ECCKey ** ppKey )

Zeroes and frees memory allocated within and for an ECCKey.

Parameters

ppKey Pointer to the location of the key that will be deleted.

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

◆ EC_deletePrimeCurveCombsAndMutexes()

MOC_EXTERN MSTATUS EC_deletePrimeCurveCombsAndMutexes ( void )

Zeros and frees globally stored combs and mutexes. These are the mutexes created by the EC_createPrimeCurveMutexes method. The comb's will have been generated as needed by the ECDSA signing algorithm.

To use this method one must define ENABLE_MOCANA_SIGNED_ODD_COMB_PERSIST and not have DISABLE_MOCANA_SIGNED_ODD_COMB not defined.

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

◆ EC_equalKey()

MOC_EXTERN MSTATUS EC_equalKey	(	const ECCKey *	pKey1,
		const ECCKey *	pKey2,
		byteBoolean *	res
	)

Tests whether two ECCKeys have identical public keys. The private key portions for private keys are ignored.

Parameters

pKey1	The first input key.
pKey2	The second input key.
res	Contents will be set to TRUE if the two public keys are the same point on the curve and FALSE otherwise.

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

◆ EC_generateKeyPair()

MOC_EXTERN MSTATUS EC_generateKeyPair	(	PEllipticCurvePtr	pEC,
		RNGFun	rngFun,
		void *	rngArg,
		PFEPtr	k,
		PFEPtr	pQx,
		PFEPtr	pQy
	)

Generates a new ECC private/public key pair in prime field element forms.

Parameters

pEC	The curve to associate with the key. This is should be one of the globally defined prime field curves.

EC_P192 (if enabled) EC_P224 EC_P256 EC_P384 EC_P521

Parameters

rngFun	Function pointer callback to a method that will provide random entropy.
rngArg	Optional argument that may be needed by the `rngFun` provided.
k	The resuling private key scalar in a prime field element form.
pQx	The resulting public key point's X coordinate.
pQy	The resulting public key point's Y coordinate.

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

◆ EC_getPointByteStringLen()

MOC_EXTERN MSTATUS EC_getPointByteStringLen	(	PEllipticCurvePtr	pEC,
		sbyte4 *	pLen
	)

Gets the length in bytes of an arbitrary point's uncompressed form. All points on the curve will have this same length (ie will be properly zero padded if neccessary).

Parameters

pEC	Pointer to the globally defined prime curve in question.
pLen	Contents will be set to the number of bytes in an uncompressed form point.

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

◆ EC_getUnderlyingField()

MOC_EXTERN PrimeFieldPtr EC_getUnderlyingField ( PEllipticCurvePtr pEC )

Gets the underlying prime field associated with a prime curve.

Parameters

pEC	Pointer to the globally defined prime curve in question.

Returns: A pointer to the global prime field associated with the input curve.

◆ EC_multiplyPoint()

MOC_EXTERN MSTATUS EC_multiplyPoint	(	PrimeFieldPtr	pPF,
		PFEPtr	pResX,
		PFEPtr	pResY,
		ConstPFEPtr	k,
		ConstPFEPtr	pX,
		ConstPFEPtr	pY
	)

Computes a scalar-point multiplication on a prime curve. It is not checked that the input coordinates (pX,pY) represent a valid point.

Parameters

pPF	The globally defined prime field associated with the prime curve.
pResX	The resulting point's X coordinate.
pResY	The resulting point's Y coordinate.
k	The input scalar stored in the form of a prime field element. This need not be a reduced prime field element.
pX	The input point's X coordinate.
pY	The input point's Y coordinate.

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

◆ EC_newKey()

MOC_EXTERN MSTATUS EC_newKey	(	PEllipticCurvePtr	pEC,
		ECCKey **	ppNewKey
	)

Allocates a new ECCKey instance. Be sure to call EC_deleteKey when done in order to free the allocated memory.

Parameters

pEC	One of the globally defined prime field curves. EC_P192 (if enabled) EC_P224 EC_P256 EC_P384 EC_P521
ppNewKey	Pointer to the location that will receive the new key.

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

◆ EC_pointToByteString()

MOC_EXTERN MSTATUS EC_pointToByteString	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	pX,
		ConstPFEPtr	pY,
		ubyte **	s,
		sbyte4 *	pLen
	)

Allocates a buffer and converts a point on the curve to an uncompressed form byte array. This byte array will begin with a 0x04 byte followed by the X and Y coordinates in Big Endian, each of length equal to the standard prime field element length. Be sure to FREE this buffer when done with it.

Parameters

pEC	Pointer to the globally defined prime curve in question.
pX	The point's X coordinate.
pY	The point's Y coordinate.
s	Location of the newly allocated buffer that will hold the resulting uncompressed form point.
pLen	Contents will be set to the length of the newly allocated buffer in bytes.

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

◆ EC_precomputeComb()

MOC_EXTERN MSTATUS EC_precomputeComb	(	PrimeFieldPtr	pPF,
		ConstPFEPtr	pQx,
		ConstPFEPtr	pQy,
		sbyte4	windowSize,
		PFEPtr *	pPrecomputed
	)

Computes the comb of a point on the curve. The table created can be used to speed up multiplication of a scalar times the point in question. The table will be allocated so be sure to call EC_deleteComb to free such memory when done with it.

Parameters

pPF	The globally defined prime field associated to the curve in question.
pQx	The input point's X coordinate.
pQy	The input point's Y coordinate.
windowSize	The input window size. This must be 2 or larger and is a memory vs speed tradeoff. Generally 4 or 5 is optimal.
pPrecomputed	Pointer to the location of a newly allocated array of `PFEPtrs` representing the comb table of the input point.

To use this method one must define ENABLE_MOCANA_ECC_COMB and have ENABLE_MOCANA_SMALL_CODE_FOOTPRINT not defined.

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

◆ EC_precomputeCombOfCurve()

MOC_EXTERN MSTATUS EC_precomputeCombOfCurve	(	PEllipticCurvePtr	pEC,
		sbyte4	windowSize,
		PFEPtr *	pCurvePrecomputed
	)

Computes the comb of the curve's large cyclic group generator. The table created can be used to speed up multiplication of a scalar times the generator. The table will be allocated so be sure to call EC_deleteComb to free such memory when done with it.

Parameters

pEC	Pointer to the globally defined prime curve in question.
windowSize	The input window size. This must be 2 or larger and is a memory vs speed tradeoff. Generally 4 or 5 is optimal.
pCurvePrecomputed	Pointer to the location of a newly allocated array of `PFEPtrs` representing the comb table of the generator point.

To use this method one must define ENABLE_MOCANA_ECC_COMB and have ENABLE_MOCANA_SMALL_CODE_FOOTPRINT not defined.

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

◆ EC_setKeyParameters()

MOC_EXTERN MSTATUS EC_setKeyParameters	(	ECCKey *	pKey,
		const ubyte *	point,
		ubyte4	pointLen,
		const ubyte *	scalar,
		ubyte4	scalarLen
	)

Sets the key parameters of an ECCKey. This method can set a public key by passing in NULL for the scalar parameter, or it can be used to set a private key by passing the scalar in along with the public point.

Parameters

pKey	Pointer to a previously allocated key.
point	Buffer holding the point in an uncompressed form. This form must begin with a 0x04 byte followed by the X and Y coordinates in Big Endian, each zero padded to the proper prime field element length. If not provided, the public key will still be set in pKey from the private key.
pointLen	The length of the point buffer in bytes.
scalar	Optional. The scalar as Big Endian byte array. If this is NULL then the key type will be public, and otherwise private. Note this value is required to be less than the prime number associated with the curve in question.
scalarLen	The length of the scalar in bytes.

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

◆ EC_setPointToByteString()

MOC_EXTERN MSTATUS EC_setPointToByteString	(	PEllipticCurvePtr	pEC,
		const ubyte *	s,
		sbyte4	len,
		PFEPtr	pX,
		PFEPtr	pY
	)

Converts a byte array form uncompressed point to the point in the form of two prime field elements.

Parameters

pEC	Pointer to the globally defined prime curve in question.
s	Buffer holding the uncompressed form point. This should begin with an 0x04 byte followed by X and Y in Big Endian each properly padded to the prime field's element length.
len	The length of the buffer s in bytes.
pX	The resulting X coordinate as a prime field element.
pY	The resulting Y coordinate as a prime field element.

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

◆ EC_setPrivateKey()

MOC_EXTERN MSTATUS EC_setPrivateKey	(	ECCKey *	pKey,
		ubyte *	pScalar,
		ubyte4	scalarLen
	)

Sets the private key parameter of an ECCKey. The public key will be left NULL.

Parameters

pKey	Pointer to a previously allocated key.
scalar	The scalar as Big Endian byte array.
scalarLen	The length of the scalar in bytes.

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

◆ EC_verifyKeyPair()

MOC_EXTERN MSTATUS EC_verifyKeyPair	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	k,
		ConstPFEPtr	pQx,
		ConstPFEPtr	pQy
	)

Verifies that a given private key, ie a scalar, is associated with a given public key, ie a point.

Parameters

pEC	Pointer to the globally defined prime curve in question.
k	The private key scalar stored in the form of a prime field element.
pQx	The public key point's X coordinate.
pQy	The public key point's Y coordinate.

Returns: OK (0) if successful and the input consists of a valid key pair, otherwise a negative number error code from merrors.h

◆ EC_verifyPoint()

MOC_EXTERN MSTATUS EC_verifyPoint	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	pQx,
		ConstPFEPtr	pQy
	)

Verifies that a point is a valid point on the curve. This method is the same as EC_verifyPublicKey execpt the input is not validated as reduced prime field elements. Non-reduced elements will produce garbage results.

Parameters

pEC	Pointer to the globally defined prime curve in question.
pQx	The public key point's X coordinate.
pQy	The public key point's Y coordinate.

Returns: OK (0) if successful and the input consists of a valid point, otherwise a negative number error code from merrors.h

◆ EC_verifyPublicKey()

MOC_EXTERN MSTATUS EC_verifyPublicKey	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	pQx,
		ConstPFEPtr	pQy
	)

Verifies that a public key point is a valid point on the curve. This method is the same as EC_verifyPoint except the input is also validated to be reduced prime field elements.

Parameters

pEC	Pointer to the globally defined prime curve in question.
pQx	The public key point's X coordinate.
pQy	The public key point's Y coordinate.

Returns: OK (0) if successful and the input consists of a valid public key point, otherwise a negative number error code from merrors.h

◆ EC_writePointToBuffer()

MOC_EXTERN MSTATUS EC_writePointToBuffer	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	pX,
		ConstPFEPtr	pY,
		ubyte *	s,
		sbyte4	len
	)

Converts a point on the curve to an uncompressed form byte array in a previously existing buffer. This byte array will begin with a 0x04 byte followed by the X and Y coordinates in Big Endian, each of length equal to the standard prime field element length.

Parameters

pEC	Pointer to the globally defined prime curve in question.
pX	The point's X coordinate.
pY	The point's Y coordinate.
s	Buffer that will hold the resulting uncompressed form point.
len	The length of the buffer s in bytes.

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

◆ ECDH_generateSharedSecret()

MOC_EXTERN MSTATUS ECDH_generateSharedSecret	(	PEllipticCurvePtr	pEC,
		const ubyte *	pointByteString,
		sbyte4	pointByteStringLen,
		ConstPFEPtr	scalarMultiplier,
		ubyte **	sharedSecret,
		sbyte4 *	sharedSecretLen
	)

Generates a Diffie-Hellman shared secret from an uncompressed form public key and places it in a newly allocated buffer. The shared secret will consist of just the X-coordinate in Big Endian form with leading zeros preserved. Be sure to FREE this buffer when done with it.

Parameters

pEC	Pointer to the globally defined prime curve.
pointByteString	The other party's public key as an uncompressed form byte array. This should begin with an 0x04 byte followed by X and Y in Big Endian each properly padded to the prime field's element length.
pointByteStringLen	The length of the uncompressed form byte array in bytes.
scalarMultiplier	Our private key scalar stored as a prime field element.
sharedSecret	Pointer to the location of the newly allocated buffer that will store the shared secret.
sharedSecretLen	Contents will be set to the length of the shared secret in bytes.

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

◆ ECDH_generateSharedSecretAux()

MOC_EXTERN MSTATUS ECDH_generateSharedSecretAux	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	pX,
		ConstPFEPtr	pY,
		ConstPFEPtr	scalarMultiplier,
		ubyte **	sharedSecret,
		sbyte4 *	sharedSecretLen,
		sbyte4	flag
	)

Generates a Diffie-Hellman shared secret and places it in a newly allocated buffer. Be sure to FREE this buffer when done with it.

Parameters

pEC	Pointer to the globally defined prime curve.
pX	The other party's public key's X-coordinate.
pY	The other party's public key's Y-coordinate.
scalarMultiplier	Our private key scalar stored as a prime field element.
sharedSecret	Pointer to the location of the newly allocated buffer that will store the shared secret.
sharedSecretLen	Contents will be set to the length of the shared secret in bytes.
flag	Use `ECDH_X_CORD_ONLY` (1) for a shared secret consisting of just the X-coordinate in Big Endian form with leading zeros preserved (typically called Z). Use `ECDH_XY_CORD` (0) for a shared secret consisting of a concatenated X and Y in such form.

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

◆ ECDH_keyAgreementSchemePrimeCurve()

MOC_EXTERN MSTATUS ECDH_keyAgreementSchemePrimeCurve	(	ubyte4	mode,
		ECCKey *	pStatic,
		ECCKey *	pEphemeral,
		ubyte *	pOtherPartysStatic,
		ubyte4	otherStaticLen,
		ubyte *	pOtherPartysEphemeral,
		ubyte4	otherEphemeralLen,
		ubyte **	ppSharedSecret,
		ubyte4 *	pSharedSecretLen
	)

Generates a Diffie-Hellman shared secret via one of the major modes. This method allocates a buffer to hold the secret. Be sure to FREE this buffer when done with it.

To use this method one must define ENABLE_MOCANA_ECDH_MODES

Parameters

mode	One of the following macro values `FULL_UNIFIED` `FULL_MQV` `EPHEMERAL_UNIFIED` `ONE_PASS_UNIFIED_U` `ONE_PASS_UNIFIED_V` `ONE_PASS_MQV_U` `ONE_PASS_MQV_V` `ONE_PASS_DH_U` `ONE_PASS_DH_V` `STATIC_UNIFIED`
pStatic	Our private static key.
pEphemeral	Our private ephemeral key.
pOtherPartysStatic	The other party's static public key as an uncompressed form byte array.
otherStaticLen	The length of the uncompressed form static key byte array in bytes.
pOtherPartysEphemeral	The other party's ephemeral public key as an uncompressed form byte array.
otherEphemeralLen	The length of the uncompressed form ephemeral key byte array in bytes.
ppSharedSecret	Pointer to the location of the newly allocated buffer that will store the shared secret.
pSharedSecretLen	Contents will be set to the length of the shared secret in bytes.

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

◆ ECDSA_signDigestAux()

MOC_EXTERN MSTATUS ECDSA_signDigestAux	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	d,
		RNGFun	rngFun,
		void *	rngArg,
		const ubyte *	hash,
		ubyte4	hashLen,
		PFEPtr	r,
		PFEPtr	s
	)

Signs a message digest via the ECDSA signature algorithm. The computed signature (r,s) will be in the form of prime field elements.

Parameters

pEC	Pointer to the globally defined prime curve.
d	The private key scalar stored as a prime field element.
rngFun	Function pointer callback to a method that will provide random entropy.
rngArg	Optional argument that may be needed by the `rngFun` provided.
hash	Buffer holding the digest of the message to be signed.
hashLen	The length of the message digest in bytes.
r	The resulting signature's r value stored as a prime field element.
s	The resulting signature's s value stored as a prime field element.

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

◆ ECDSA_verifySignature()

MOC_EXTERN MSTATUS ECDSA_verifySignature	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	pPublicKeyX,
		ConstPFEPtr	pPublicKeyY,
		const ubyte *	hash,
		ubyte4	hashLen,
		ConstPFEPtr	r,
		ConstPFEPtr	s
	)

Verifies a message digest via the ECDSA signature algorithm.

Parameters

pEC	Pointer to the globally defined prime curve.
pPublicKeyX	The public key's X-coordinate.
pPublicKeyY	The public key's Y-coordinate.
hash	Buffer holding the digest of the message to be verified.
hashLen	The length of the message digest in bytes.
r	The input signature's r value stored as a prime field element.
s	The input signature's s value stored as a prime field element.

Returns: OK (0) if successful AND the signature is valid, otherwise a negative number error code from merrors.h

◆ ECDSA_verifySignatureEx()

MOC_EXTERN MSTATUS ECDSA_verifySignatureEx	(	PEllipticCurvePtr	pEC,
		ConstPFEPtr	pPublicKeyX,
		ConstPFEPtr	pPublicKeyY,
		const ubyte *	hash,
		ubyte4	hashLen,
		sbyte4	curveWinSize,
		ConstPFEPtr	pCurvePrecomp,
		sbyte4	pubKeyWinSize,
		ConstPFEPtr	pPubKeyPrecomp,
		ConstPFEPtr	r,
		ConstPFEPtr	s
	)

Verifies a message digest via the ECDSA signature algorithm using provided combs. The comb(s) may have been generated in the signing phase and stored alongside the public key. This will greatly improve efficiency in the verification algorithm.

Parameters

pEC	Pointer to the globally defined prime curve.
pPublicKeyX	The public key's X-coordinate.
pPublicKeyY	The public key's Y-coordinate.
hash	Buffer holding the digest of the message to be verified.
hashLen	The length of the message digest in bytes.
curveWinSize	The window size of the input pCurvePrecomp comb. Use 0 if no comb is provided.
pCurvePrecomp	Optional pointer to a comb of the curve's large cyclic group generator.
pubKeyWinSize	The window size of the input pPubKeyPrecomp comb. Use 0 if no comb is provided.
pPubKeyPrecomp	Optional pointer to a comb of the public key point.
r	The input signature's r value stored as a prime field element.
s	The input signature's s value stored as a prime field element.

Returns: OK (0) if successful AND the signature is valid, otherwise a negative number error code from merrors.h

Typedefs

Functions

Variables

Detailed Description

Function Documentation

◆ EC_addMultiplyPoint()

◆ EC_byteStringToPoint()

◆ EC_cloneKey()

◆ EC_combSize()

◆ EC_compareEllipticCurves()

◆ EC_computeYFromX()

◆ EC_createPrimeCurveMutexes()

◆ EC_deleteComb()

◆ EC_deleteKey()

◆ EC_deletePrimeCurveCombsAndMutexes()

◆ EC_equalKey()

◆ EC_generateKeyPair()

◆ EC_getPointByteStringLen()

◆ EC_getUnderlyingField()

◆ EC_multiplyPoint()

◆ EC_newKey()

◆ EC_pointToByteString()

◆ EC_precomputeComb()

◆ EC_precomputeCombOfCurve()

◆ EC_setKeyParameters()

◆ EC_setPointToByteString()

◆ EC_setPrivateKey()

◆ EC_verifyKeyPair()

◆ EC_verifyPoint()

◆ EC_verifyPublicKey()

◆ EC_writePointToBuffer()

◆ ECDH_generateSharedSecret()

◆ ECDH_generateSharedSecretAux()

◆ ECDH_keyAgreementSchemePrimeCurve()

◆ ECDSA_signDigestAux()

◆ ECDSA_verifySignature()

◆ ECDSA_verifySignatureEx()