TrustCore SDK Crypto Interface API reference  version 2.0
crypto_interface_ecc.h File Reference

Cryptographic Interface header file for declaring ECC functions. More...

Go to the source code of this file.

Functions

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_cloneKeyAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey **ppNewKey, ECCKey *pSrc)
 Allocates and clones an existing key. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_createCombMutexes (void)
 Creates mutex's for ecc combs so that only a single thread can create and persist a globally used comb. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_deleteAllCombsAndMutexes (void)
 Delete's all created global combs for ecc and the associated mutex's. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_deleteKeyAux (ECCKey **ppKey)
 Free an ECC Key. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_equalKeyAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey1, ECCKey *pKey2, byteBoolean *pRes)
 Tests if the public key portion of two ECCKeys are equal. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_freeKeyTemplateAux (ECCKey *pKey, MEccKeyTemplate *pTemplate)
 Frees the key data stored within the provided template structure. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_generateKeyPairAlloc (MOC_ECC(hwAccelDescr hwAccelCtx) ubyte4 curveId, void **ppNewKey, RNGFun rngFun, void *rngArg, ubyte4 keyType, void *pKeyAttributes)
 Generate a key pair on the curve specified from the curve id. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_generateKeyPairAllocAux (MOC_ECC(hwAccelDescr hwAccelCtx) ubyte4 curveId, ECCKey **ppKey, RNGFun rngFun, void *pRngFunArg)
 Generate a key pair on the curve specified from the curve id. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_generateKeyPairAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, RNGFun rngFun, void *pRngFunArg)
 Generate a key pair previously allocated with CRYPTO_INTERFACE_EC_newKeyAux. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getCurveIdFromKeyAux (ECCKey *pKey, ubyte4 *pCurveId)
 Retrieve the curve identifier from a key previously created with CRYPTO_INTERFACE_EC_newKeyAux or generated with CRYPTO_INTERFACE_EC_generateKeyPairAllocAux. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getElementByteStringLenAux (ECCKey *pKey, ubyte4 *pLen)
 Get the length of an individual prime field element when represented as a bytestring. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getKeyParametersAllocAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, MEccKeyTemplate *pTemplate, ubyte reqType)
 Allocates and sets the appropriate keys parameters of pTemplate with that from the passed in pKey. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getPointByteStringLenAux (ECCKey *pKey, ubyte4 *pLen)
 Get the length of the bytestring representation of the public key, typically used to determine the buffer size for CRYPTO_INTERFACE_EC_writePublicKeyToBufferAux. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getPointByteStringLenByCurveId (ubyte4 curveId, ubyte4 *pLen)
 Get the length of the public value based on the curve ID. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_isKeyPrivate (ECCKey *pKey, intBoolean *pResult)
 Determines if a key is a private key or a public key. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_newKeyAux (ubyte4 curveId, ECCKey **ppNewKey)
 Create a new key from a curve identifier. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_newKeyEx (ubyte4 curveId, ECCKey **ppNewKey, ubyte4 keyType, void *pKeyAttributes)
 Create a new key from a curve identifier. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_newPublicKeyFromByteStringAux (MOC_ECC(hwAccelDescr hwAccelCtx) ubyte4 curveId, ECCKey **ppNewKey, ubyte *pByteString, ubyte4 byteStringLen)
 Create a new ECC public key from the bytestring representation of public point. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_setKeyParametersAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, ubyte *pPoint, ubyte4 pointLen, ubyte *pScalar, ubyte4 scalarLen)
 Sets the public key portion of an ECCKey and optionally the private key portion. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_setPrivateKey (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, ubyte *pScalar, ubyte4 scalarLen)
 Sets the private key parameter of an ECCKey. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_verifyKeyPairAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPrivateKey, ECCKey *pPublicKey, byteBoolean *pVfy)
 Validate that a given public and private key are consistent. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_verifyPublicKeyAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, byteBoolean *pIsValid)
 Check that the public key is valid, which ensures the public point is valid and lies on the curve. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_writePublicKeyToBufferAllocAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, ubyte **ppBuffer, ubyte4 *pBufferSize)
 Allocate a new buffer and writes the public point to it. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_writePublicKeyToBufferAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, ubyte *pBuffer, ubyte4 bufferSize)
 Write the public point to a buffer. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDH_generateSharedSecretFromKeysAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPrivateKey, ECCKey *pPublicKey, ubyte **ppSharedSecret, ubyte4 *pSharedSecretLen, sbyte4 flag, void *pKdfInfo)
 Generate an ECDH shared secret from a public and private key. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDH_generateSharedSecretFromPublicByteStringAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPrivateKey, ubyte *pPublicPointByteString, ubyte4 pointByteStringLen, ubyte **ppSharedSecret, ubyte4 *pSharedSecretLen, sbyte4 flag, void *pKdfInfo)
 Generate an ECDH shared secret from private key and bytestring representation of the public point. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDH_keyAgreementScheme (MOC_ECC(hwAccelDescr hwAccelCtx) 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 CRYPTO_INTERFACE_ECDSA_finalVerifyExt (MOC_ECC(hwAccelDescr hwAccelCtx) ECDSA_CTX *pCtx, ubyte4 *pVerifyFailures, void *pExtCtx)
 Finalizes a context for an ECDSA verify operation and computes whether the signature is valid. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_initVerifyExt (MOC_ECC(hwAccelDescr hwAccelCtx) ECDSA_CTX *pCtx, ECCKey *pPublicKey, ubyte hashAlgo, ubyte *pSignature, ubyte4 signatureLen, void *pExtCtx)
 Initializes a context for an ECDSA verify operation. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_signDigestAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, RNGFun rngFun, void *rngArg, ubyte *pHash, ubyte4 hashLen, ubyte *pSignature, ubyte4 bufferSize, ubyte4 *pSignatureLen)
 Perform an ECDSA signing operation on the provided digest, producing the raw signature value. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_signMessageExt (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPrivateKey, RNGFun rngFUN, void *pRngArg, ubyte hashAlgo, ubyte *pMessage, ubyte4 messageLen, ubyte *pSignature, ubyte4 bufferSize, ubyte4 *pSignatureLen, void *pExtCtx)
 Performs an ECDSA sign operation on the message provided. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_updateVerifyExt (MOC_ECC(hwAccelDescr hwAccelCtx) ECDSA_CTX *pCtx, ubyte *pMessage, ubyte4 messageLen, void *pExtCtx)
 Updates a context for an ECDSA verify operation. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_verifyMessageExt (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPublicKey, ubyte hashAlgo, ubyte *pMessage, ubyte4 messageLen, ubyte *pSignature, ubyte4 signatureLen, ubyte4 *pVerifyFailures, void *pExtCtx)
 Performs an ECDSA verify operation on the message provided. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_verifySignatureDigestAux (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPublicKey, ubyte *pHash, ubyte4 hashLen, ubyte *pR, ubyte4 rLen, ubyte *pS, ubyte4 sLen, ubyte4 *pVerifyFailures)
 Verify individual signature values with the provided public key. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EdDSA_signInput (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, ubyte *pInput, ubyte4 inputLen, byteBoolean isPreHash, ubyte *pCtx, ubyte4 ctxLen, ubyte *pSignature, ubyte4 bufferSize, ubyte4 *pSignatureLen, void *pExtCtx)
 Perform an EdDSA signing operation on the provided input. More...
 
MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EdDSA_verifyInput (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pKey, ubyte *pInput, ubyte4 inputLen, byteBoolean isPreHash, ubyte *pCtx, ubyte4 ctxLen, ubyte *pSignature, ubyte4 signatureLen, ubyte4 *pVerifyFailures, void *pExtCtx)
 Performs an EdDSA verify operation on the input provided. More...
 

Detailed Description

Add details here.

crypto_interface_ecc.h

Function Documentation

◆ CRYPTO_INTERFACE_EC_cloneKeyAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_cloneKeyAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey **  ppNewKey,
ECCKey *  pSrc 
)

When done with the clone it is the callers responsibility to free the memory of it by calling CRYPTO_INTERFACE_EC_deleteKeyAux.

Parameters
ppNewKeyPointer to the location that will receive the new clone.
pSrcPointer to the existing key that is to be cloned.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_createCombMutexes()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_createCombMutexes ( void  )

This method should only be called once at the beginning of your application.

Returns
OK (0) for successful completion. Otherwise a negative number error code from merrors.h is returned.

◆ CRYPTO_INTERFACE_EC_deleteAllCombsAndMutexes()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_deleteAllCombsAndMutexes ( void  )

This method should only be called once at the end of your application.

Returns
OK (0) for successful completion. Otherwise a negative number error code from merrors.h is returned.

◆ CRYPTO_INTERFACE_EC_deleteKeyAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_deleteKeyAux ( ECCKey **  ppKey)
Parameters
ppKeyDouble pointer to the key to be deleted.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_equalKeyAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_equalKeyAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey1,
ECCKey *  pKey2,
byteBoolean *  pRes 
)

WARNING: This does not compare the private key portion.

Parameters
pKey1Pointer to the first key.
pKey2Pointer to the second key.
pResPointer to a byteBoolean that will be set to TRUE if the public key is identical and FALSE otherwise.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_freeKeyTemplateAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_freeKeyTemplateAux ( ECCKey *  pKey,
MEccKeyTemplate *  pTemplate 
)
Parameters
pKeyPointer to the original key the data was retrieved from.
pTemplatePointer to a key template structure previously filled using CRYPTO_INTERFACE_EC_getKeyParametersAllocAux.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_generateKeyPairAlloc()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_generateKeyPairAlloc ( MOC_ECC(hwAccelDescr hwAccelCtx) ubyte4  curveId,
void **  ppNewKey,
RNGFun  rngFun,
void *  rngArg,
ubyte4  keyType,
void *  pKeyAttributes 
)

Note that in general this should be used instead of EC_generateKeyPairEx. This function will allocate the ECCKey for you, it is the callers responsibility to free the key object using EC_deleteKey. Note that this API can generate both TAP and SW keys.

Parameters
curveIdOne of the cid_EC_* values from ca_mgmt.h indicating the curve this key should be created on.
ppNewKeyPointer to the location that will recieve the generated key.
rngFunFunction pointer for generating the random values. If you have a randomContext you would like to use, simply pass RANDOM_rngFun for this param and the randomContext as the rngArg.
rngArgArgument to the rngFun. If you have a randomContext you would like to use, pass in RANDOM_rngFun for the rngFun and pass the randomContext here as the argument.
keyTypeThe key type, must be akt_tap_ecc if this is a TAP key, and akt_ecc otherwise.
pKeyAttributesPointer to a key attribute structure.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_generateKeyPairAllocAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_generateKeyPairAllocAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ubyte4  curveId,
ECCKey **  ppKey,
RNGFun  rngFun,
void *  pRngFunArg 
)

Note that in general this should be used instead of CRYPTO_INTERFACE_EC_generateKeyPairAux. This function will allocate the ECCKey for you, it is the callers responsibility to free the key object using CRYPTO_INTERFACE_EC_deleteKeyAux.

Parameters
curveIdOne of the cid_EC_* values from ca_mgmt.h indicating the curve this key should be created on.
ppKeyPointer to the location that will receive the generated key.
rngFunFunction pointer for generating the random values. If you have a randomContext you would like to use, simply pass RANDOM_rngFun for this param and the randomContext as the rngArg.
pRngFunArgArgument to the rngFun. If you have a randomContext you would like to use, pass in RANDOM_rngFun for the rngFun and pass the randomContext here as the argument.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_generateKeyPairAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_generateKeyPairAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
RNGFun  rngFun,
void *  pRngFunArg 
)

Note that in general the CRYPTO_INTERFACE_EC_generateKeyPairAllocAux method is recommended for generation.

Parameters
pKeyPointer to an ECCKey shell previously allocated with CRYPTO_INTERFACE_EC_newKeyAux.
rngFunFunction pointer for generating the random values. If you have a randomContext you would like to use, simply pass RANDOM_rngFun for this param and the randomContext as the rngArg.
pRngFunArgArgument to the rngFun. If you have a randomContext you would like to use, pass in RANDOM_rngFun for the rngFun and pass the randomContext here as the argument.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_getCurveIdFromKeyAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getCurveIdFromKeyAux ( ECCKey *  pKey,
ubyte4 *  pCurveId 
)
Parameters
pKeyThe key to retrieve the curve identifier from.
pCurveIdThe curve identifier, see ca_mgmt.h for possible values.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_getElementByteStringLenAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getElementByteStringLenAux ( ECCKey *  pKey,
ubyte4 *  pLen 
)

For Edward's edDSA curves this is the length of the compressed form, ie 32 bytes for curve25519 and 57 bytes for curve448.

Parameters
pKeyThe key to retrieve the element bytestring length from.
pLenPointer to the location that will receive the element length.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_getKeyParametersAllocAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getKeyParametersAllocAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
MEccKeyTemplate *  pTemplate,
ubyte  reqType 
)

The caller must provide an allocated MEccKeyTemplate structure, which will then have its internal pointers allocated by this function. Note it is the callers responsibility to free this memory using CRYPTO_INTERFACE_EC_freeKeyTemplateAux. keyType should be one of MOC_GET_PUBLIC_KEY_DATA or MOC_GET_PRIVATE_KEY_DATA. The latter option will get both the private and public key parameters and as such can only be used with a private key. Retrieving the public data from a private key is allowed, retrieving private data from a public key is impossible and will result in an error. See the documentation for MEccKeyTemplate in capasym.h for more info on the format of the received key data.

Parameters
pKeyThe key to retrieve data from.
pTemplatePointer to an existing MEccKeyTemplate structure, the internal pointers within the structure will be allocated by this function.
keyTypeType of key data to receive, must be one of MOC_GET_PUBLIC_KEY_DATA or MOC_GET_PRIVATE_KEY_DATA.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_getPointByteStringLenAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getPointByteStringLenAux ( ECCKey *  pKey,
ubyte4 *  pLen 
)

For Edward's curves this is the length of the usual compressed public key form.

Parameters
pKeyThe key to retrieve the element bytestring length from.
pLenPointer to the location that will receive the point length.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_getPointByteStringLenByCurveId()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_getPointByteStringLenByCurveId ( ubyte4  curveId,
ubyte4 *  pLen 
)

Use this API with the cid_EC_* curve IDs.

Parameters
curveIdOne of the cid_EC_* values from ca_mgmt.h indicating the curve the length should be retrieved from.
pLenPointer to the location that will receive the point length.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_isKeyPrivate()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_isKeyPrivate ( ECCKey *  pKey,
intBoolean *  pResult 
)
Parameters
pKeyPointer to a previously existing key
pResultWill be set to TRUE if a private key, FALSE if a public key
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_newKeyAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_newKeyAux ( ubyte4  curveId,
ECCKey **  ppNewKey 
)

This function will allocate a new key object, it is the callers responsibility to free this memory by calling EC_deleteKey. Note that this API can only create SW keys.

Parameters
curveIdOne of the cid_EC_* values from ca_mgmt.h indicating the curve this key should be created on.
ppNewKeyPointer to the location that will recieve the new key.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_newKeyEx()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_newKeyEx ( ubyte4  curveId,
ECCKey **  ppNewKey,
ubyte4  keyType,
void *  pKeyAttributes 
)

This function will allocate a new key object, it is the callers responsibility to free this memory by calling CRYPTO_INTERFACE_EC_deleteKeyAux.

Parameters
curveIdOne of the cid_EC_* values from ca_mgmt.h indicating the curve this key should be created on.
ppNewKeyPointer to the location that will receive the new key.
keyTypeThe key type, must be akt_tap_ecc if this is a TAP key, and akt_ecc otherwise.
pKeyAttributesPointer to a key attribute structure.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_newPublicKeyFromByteStringAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_newPublicKeyFromByteStringAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ubyte4  curveId,
ECCKey **  ppNewKey,
ubyte *  pByteString,
ubyte4  byteStringLen 
)

For prime curves the public key must be encoded in the uncompressed form, ie the public key encoding must be a single byte to indicate compression status, always 0x04 for this function, followed by public values X and Y as big endian bytestrings, zero padded to element length if necessary. This format is described in the Standards for Efficient Cryptography 1: Elliptic Curve Cryptography Ver 1.9 section 2.3.3. For Edward's form curves the public key must be in the usual compressed form.

Parameters
curveIdOne of the cid_EC_* values from ca_mgmt.h indicating the curve this key should be created on.
ppNewKeyPointer to the location that will receive the new public key.
pByteStringPointer to a bytestring representation of an ECC public key.
byteStringLenThe length in bytes of the bytestring.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_setKeyParametersAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_setKeyParametersAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
ubyte *  pPoint,
ubyte4  pointLen,
ubyte *  pScalar,
ubyte4  scalarLen 
)

If the private key portion, ie pScalar, is provided, the key will be treated as a private key, and otherwise it will be treated as a public key.

Parameters
pKeyPointer to a previously allocated key.
pPointPointer to a buffer representing the public key point. For prime curves this is in an uncompressed form, ie the uncompressed form byte 0x04 followed by x and then y in Big Endian binary. For Edward's curves this is the usual Little Endian compressed form. If not provided, the public key will still be set in pKey from the private key.
pointLenThe length of the pPoint buffer in bytes.
pScalarPointer to a buffer representing the private key scalar. For prime curves this is in Big Endian. For Edward's curves this is the usual Little Endian based form. This parameter is optional and may be NULL.
scalarLenThe length of the pScalar buffer in bytes.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_setPrivateKey()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_setPrivateKey ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
ubyte *  pScalar,
ubyte4  scalarLen 
)

Sets the private key parameter of an ECCKey. The public key will be left empty. This API is not available for EdDSA keys.

Parameters
pKeyPointer to a previously allocated key.
pScalarPointer to a buffer representing the private key scalar. For prime curves this is in Big Endian. For Edward's curves this is the usual Little Endian based form.
scalarLenThe length of the scalar in bytes.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_verifyKeyPairAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_verifyKeyPairAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pPrivateKey,
ECCKey *  pPublicKey,
byteBoolean *  pVfy 
)

That is to say, this funciton verifies that k * G = Q, where k is the private key scalar, G is generator of the curve, and Q is the public key point. If no public key is provided then the private key is checked for internal consistency.

Parameters
pPrivateKeyThe private value to check against, if no public key is provided then this key will also be used for the public values.
pPublicKeyThe optional public key to check.
pVfyPointer to the boolean that will receive the verification result, TRUE if the keys are consistent and FALSE otherwise.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_verifyPublicKeyAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_verifyPublicKeyAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
byteBoolean *  pIsValid 
)

For Edward's edDH curves every compressed for public key is valid and pIsValid is always set to TRUE.

Parameters
pKeyThe public key to be verified.
pIsValidPointer to the byteBoolean that will receive the result of the verification check, TRUE if the provided key is valid and false otherwise.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_writePublicKeyToBufferAllocAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_writePublicKeyToBufferAllocAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
ubyte **  ppBuffer,
ubyte4 *  pBufferSize 
)

For prime curves the public key is encoded as a single byte to indicate compression status, which is always 0x04 (uncompressed) for this function, followed by public values X and Y as big endian bytestrings, zero padded to element length if necessary. This format is described in the Standards for Efficient Cryptography 1: Elliptic Curve Cryptography Ver 1.9 section 2.3.3. For Edward's form curves the usual compressed form public key is written.

Parameters
pKeyThe key from which the public values are to be extracted and written to the provided buffer.
ppBufferDouble pointer that will be allocated and filled with the bytestring representation of the public key.
pBufferSizeThe size in bytes of bytestring representation of the public key.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EC_writePublicKeyToBufferAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EC_writePublicKeyToBufferAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
ubyte *  pBuffer,
ubyte4  bufferSize 
)

The function CRYPTO_INTERFACE_EC_getPointByteStringLenAux can be used to determine how large the public key buffer needs to be. For prime curves the public key is encoded as a single byte to indicate compression status, which is always 0x04 (uncompressed) for this function, followed by public values X and Y as big endian bytestrings, zero padded to element length if necessary. This format is described in the Standards for Efficient Cryptography 1: Elliptic Curve Cryptography Ver 1.9 section 2.3.3. For Edward's form curves the usual compressed form public key is written.

Parameters
pKeyThe key from which the public values are to be extracted and written to the provided buffer.
pBufferPointer to allocated memory that will receive the encoded public key.
bufferSizeThe size in bytes of the memory block pointed to by pBuffer, must be large enough for the encoded public key. You can use CRYPTO_INTERFACE_EC_getPointByteStringLenAux to determine this length.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_ECDH_generateSharedSecretFromKeysAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDH_generateSharedSecretFromKeysAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pPrivateKey,
ECCKey *  pPublicKey,
ubyte **  ppSharedSecret,
ubyte4 *  pSharedSecretLen,
sbyte4  flag,
void *  pKdfInfo 
)

If the keys passed in are prime curve keys then this is the classical ECDH algorithm. If the keys are Edward's form keys then this is the edDH algorithm (which only differs from ECDH in the curve form and key forms). Note that this function will allocate the shared secret and it is the callers responsibility to free that memory using MOC_FREE.

Parameters
pPrivateKeyPointer to the private key for this operation.
pPublicKeyPointer to the public key for this operation.
ppSharedSecretDouble pointer that will be allocated by this function and filled with the shared secret material.
pSharedSecretLenPointer to the location that will receive the length of the shared secret value in bytes.
flagFor prime curves only. Flag indicating whether to use both the x and y coordinates or just the x coordinate. A flag of 1 is for x only, a flag of 0 is for x concatenated with y. Each coordinate will be zero padded if necassary to the field element length.
pKdfInfoPointer to possible information on a KDF to apply during the secret generation process, unused at this time so simply pass NULL.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_INTERFACE_ECDH_generateSharedSecretFromPublicByteStringAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDH_generateSharedSecretFromPublicByteStringAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pPrivateKey,
ubyte *  pPublicPointByteString,
ubyte4  pointByteStringLen,
ubyte **  ppSharedSecret,
ubyte4 *  pSharedSecretLen,
sbyte4  flag,
void *  pKdfInfo 
)

If the pPrivateKey passed in is a prime curve key then this is the classical ECDH algorithm. If the key is an Edward's form key then this is the edDH algorithm (which only differs from ECDH in the curve form and key forms). For prime curves the public point must be encoded as an uncompressed point per Standards for Efficient Cryptography 1: Elliptic Curve Cryptography Ver 1.9 section 2.3.3.

Parameters
pPrivateKeyPointer to the private key for this operation.
pPointByteStringPointer to the bytestring representation of the public key to use for this operation.
pointByteStringLenLength in bytes of the public point bytestring.
ppSharedSecretDouble pointer that will be allocated by this function and filled with the shared secret material.
pSharedSecretLenPointer to the location that will receive the length of the shared secret value in bytes.
flagFor prime curves only. Flag indicating whether to use both the x and y coordinates or just the x coordinate. A flag of 1 is for x only, a flag of 0 is for x concatenated with y. Each coordinate will be zero padded if necassary to the field element length.
pKdfInfoPointer to possible information on a KDF to apply during the secret generation process, unused at this time so simply pass NULL.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_INTERFACE_ECDH_keyAgreementScheme()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDH_keyAgreementScheme ( MOC_ECC(hwAccelDescr hwAccelCtx) 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.

Parameters
modeOne 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
pStaticOur private static key.
pEphemeralOur private ephemeral key.
pOtherPartysStaticThe other party's static public key as an uncompressed form byte array.
otherStaticLenThe length of the uncompressed form static key byte array in bytes.
pOtherPartysEphemeralThe other party's ephemeral public key as an uncompressed form byte array.
otherEphemeralLenThe length of the uncompressed form ephemeral key byte array in bytes.
ppSharedSecretPointer to the location of the newly allocated buffer that will store the shared secret.
pSharedSecretLenContents 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

◆ CRYPTO_INTERFACE_ECDSA_finalVerifyExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_finalVerifyExt ( MOC_ECC(hwAccelDescr hwAccelCtx) ECDSA_CTX *  pCtx,
ubyte4 *  pVerifyFailures,
void *  pExtCtx 
)
Parameters
pCtxPointer to a previously initialized context.
pVerifyFailuresWill be set to zero for a valid signature and to a non-zero value on an invalid signature.
pExtCtxAn extended context reserved for future use.
Returns
OK (0) for successful completion of the method regardless of the validity of the signature. Otherwise a negative number error code from merrors.h is returned.

◆ CRYPTO_INTERFACE_ECDSA_initVerifyExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_initVerifyExt ( MOC_ECC(hwAccelDescr hwAccelCtx) ECDSA_CTX *  pCtx,
ECCKey *  pPublicKey,
ubyte  hashAlgo,
ubyte *  pSignature,
ubyte4  signatureLen,
void *  pExtCtx 
)

If the pPublicKey param is a prime curve key then this is the classical ECDSA algorithm. If the pPublicKey is an Edward's form key then this is the edDSA algorithm.

Parameters
pCtxPointer to the ECDSA_CTX to be initialized.
pPublicKeyPointer to the public key to be used.
hashAlgoFor prime curves only. One of the enum values in crypto.h indicating which hash algorithm should be used to digest the message.
pSignatureBuffer holding the signature to be verified.
signatureLenSize in bytes of the pSignature buffer.
pExtCtxAn extended context reserved for future use.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_ECDSA_signDigestAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_signDigestAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
RNGFun  rngFun,
void *  rngArg,
ubyte *  pHash,
ubyte4  hashLen,
ubyte *  pSignature,
ubyte4  bufferSize,
ubyte4 *  pSignatureLen 
)

This method may only be used with prime curves. The signature is represented as the concatenation of r and s as big endian bytestrings, zero padded if necessary to ensure each bytestring is exactly elementLen. If you dont know how long the signature will be, you can call this function with a NULL pSignature and a bufferSize of zero. This will result in a return code of ERR_BUFFER_TOO_SMALL and the length of the raw signature will be placed into pSignatureLen. For callers who wish to precompute the buffer size, it will always be exactly (2 * elementLen), where elementLen is the bytestring length of each element on the curve as determined by CRYPTO_INTERFACE_EC_getElementByteStringLenAux.

Parameters
pKeyThe private key to be used to sign the hash.
rngFunFunction pointer for generating the random values. If you have a randomContext you would like to use, simply pass RANDOM_rngFun for this param and the randomContext as the rngArg.
rngArgArgument to the rngFun. If you have a randomContext you would like to use, pass in RANDOM_rngFun for the rngFun and pass the randomContext here as the argument.
pHashBuffer that contains the hash to be signed.
hashLenLength in bytes of the hashed data.
pSignatureCaller allocated buffer that will receive the raw signature.
bufferSizeSize in bytes of the pSignature buffer.
pSignatureLenPointer to the location that will receive the length in bytes of the signature.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_ECDSA_signMessageExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_signMessageExt ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pPrivateKey,
RNGFun  rngFUN,
void *  pRngArg,
ubyte  hashAlgo,
ubyte *  pMessage,
ubyte4  messageLen,
ubyte *  pSignature,
ubyte4  bufferSize,
ubyte4 *  pSignatureLen,
void *  pExtCtx 
)

If the pPrivateKey param is a prime curve key then this is the classical ECDSA algorithm. If the pPrivateKey is an Edward's form key then this is the edDSA algorithm.

Parameters
pPrivateKeyPointer to the private key to be used.
rngFunFor prime curves only. Function pointer for generating the random values. If you have a randomContext you would like to use, simply pass RANDOM_rngFun for this param and the randomContext as the rngArg. Enter NULL for Edward's curves.
pRngArgFor prime curves only. Argument to the rngFun. If you have a randomContext you would like to use, pass in RANDOM_rngFun for the rngFun and pass the randomContext. here as the argument.
hashAlgoFor prime curves only. One of the enum values in crypto.h indicating which hash algorithm should be used to digest the message.
pMessageBuffer that contains the message to be signed.
messageLenLength in bytes of the message data.
pSignatureCaller allocated buffer that will receive the raw signature.
bufferSizeSize in bytes of the pSignature buffer.
pSignatureLenPointer to the location that will receive the length in bytes of the signature.
pExtCtxAn extended context reserved for future use.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_ECDSA_updateVerifyExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_updateVerifyExt ( MOC_ECC(hwAccelDescr hwAccelCtx) ECDSA_CTX *  pCtx,
ubyte *  pMessage,
ubyte4  messageLen,
void *  pExtCtx 
)

ECDSA_updateVerify may be called as many times as appropriate.

Parameters
pCtxPointer to a previously initialized context.
pMessageBuffer that contains the message or a portion of the message to be verified.
messageLenLength in bytes of this portion of the message data.
pExtCtxAn extended context reserved for future use.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_ECDSA_verifyMessageExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_verifyMessageExt ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pPublicKey,
ubyte  hashAlgo,
ubyte *  pMessage,
ubyte4  messageLen,
ubyte *  pSignature,
ubyte4  signatureLen,
ubyte4 *  pVerifyFailures,
void *  pExtCtx 
)

If the pPublicKey param is a prime curve key then this is the classical ECDSA algorithm. If the pPublicKey is an Edward's form key then this is the edDSA algorithm.

Parameters
pPublicKeyPointer to the public key to be used.
hashAlgoFor prime curves only. One of the enum values in crypto.h indicating which hash algorithm should be used to digest the message.
pMessageBuffer that contains the message to be verified.
messageLenLength in bytes of the message data.
pSignatureBuffer holding the signature to be verified.
signatureLenSize in bytes of the pSignature buffer.
pVerifyFailuresWill be set to zero for a valid signature and to a non-zero value on an invalid signature.
pExtCtxAn extended context reserved for future use.
Returns
OK (0) for successful completion of the method regardless of the validity of the signature. Otherwise a negative number error code from merrors.h is returned.

◆ CRYPTO_INTERFACE_ECDSA_verifySignatureDigestAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_ECDSA_verifySignatureDigestAux ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pPublicKey,
ubyte *  pHash,
ubyte4  hashLen,
ubyte *  pR,
ubyte4  rLen,
ubyte *  pS,
ubyte4  sLen,
ubyte4 *  pVerifyFailures 
)

This method is for prime curves only. Note that this function returns OK even if the verification failed. For this function, a non zero return code means we were not able to properly inspect the signature for verification. This could be due to invalid input such as a NULL pointer or invalid length. If the return status if OK that does not mean the signature verified, rather that we were able to properly check the provided signature. If we were able to check the signature and it didnt verify, then the value pointed to by pVerifyFailures will be non zero. If the return code is OK and the value pointed to by pVerifyFailures is zero, the signature verified.

Parameters
pPublicKeyPointer to the public key used to verify this signature.
pHashBuffer containing the original hash that was signed.
hashLenLength in bytes of the hashed data.
pRBuffer containing the R portion of the signature, encoded as a big endian bytestring.
rLenLength in bytes of the data in pR buffer.
pSBuffer containing the S portion of the signature, encoded as a big endian bytestring.
sLenLength in bytes of the data in pS buffer.
pVerifyFailuresPointer to the location that will receive the result of the verification check. If that value is zero upon return, the signature verified.
Returns
OK (0) for successful completion of the method regardless of the validity of the signature. Otherwise a negative number error code from merrors.h is returned.

◆ CRYPTO_INTERFACE_EdDSA_signInput()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EdDSA_signInput ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
ubyte *  pInput,
ubyte4  inputLen,
byteBoolean  isPreHash,
ubyte *  pCtx,
ubyte4  ctxLen,
ubyte *  pSignature,
ubyte4  bufferSize,
ubyte4 *  pSignatureLen,
void *  pExtCtx 
)

This API allows for HashEdDSA and EdDSActx mode. If you dont know how long the signature will be, you can call this function with a NULL pSignature and a bufferSize of zero. This will result in a return code of ERR_BUFFER_TOO_SMALL and the length of the raw signature will be placed into pSignatureLen.

Parameters
pKeyThe private key to be used to sign the digest.
pInputBuffer that contains the input to be signed. This is the digest for pre-hash mode, or the message otherwise.
inputLenLength in bytes of the input.
isPreHashTRUE for pre hash or HashEdDSA.
pCtxOptional. The context byte array for EdDSActx mode.
ctxLenThe context length in bytes.
pSignatureCaller allocated buffer that will receive the raw signature.
bufferSizeSize in bytes of the pSignature buffer.
pSignatureLenPointer to the location that will receive the length in bytes of the signature.
pExtCtxAn extended context reserved for future use.
Returns
OK (0) if successful, otherwise a negative number error code from merrors.h

◆ CRYPTO_INTERFACE_EdDSA_verifyInput()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_EdDSA_verifyInput ( MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *  pKey,
ubyte *  pInput,
ubyte4  inputLen,
byteBoolean  isPreHash,
ubyte *  pCtx,
ubyte4  ctxLen,
ubyte *  pSignature,
ubyte4  signatureLen,
ubyte4 *  pVerifyFailures,
void *  pExtCtx 
)

This API can be used for HashEdDSA and EdDSActx mode.

Parameters
pKeyPointer to the public key to be used.
pInputBuffer that contains the input to be verified. This is the digest for pre-hash mode, or the message otherwise.
inputLenLength in bytes of the input.
isPreHashTRUE for pre hash or HashEdDSA.
pCtxOptional. The context byte array for EdDSActx mode.
ctxLenThe context length in bytes.
pSignatureBuffer holding the signature to be verified.
signatureLenSize in bytes of the pSignature buffer.
pVerifyFailuresWill be set to zero for a valid signature and to a non-zero value on an invalid signature.
pExtCtxAn extended context reserved for future use.
Returns
OK (0) for successful completion of the method regardless of the validity of the signature. Otherwise a negative number error code from merrors.h is returned.