CmEmbedded_4c_transp CmCalculateHashMac()

Description

CmCalculateHashMac calculates message authentication codes or hashes based on an algorithm which can be selected. The related secret keys are stored in a CmContainer entry.

  • C, C++

Syntax

int CMAPIENTRY CmCalculateHashMac(HCMSysEntry hcmse, const CMHASHMAC *pcmHASHMAC, const void *pvInput, CMUINT cbInput, void *pvResult, CMUINT cbResult);

Parameter

hcmse contains an Entry Access handle opened by CmAccess2.

pcmHASHMAC contains the required information for calculate message authentication codes or hashes in the structure hmtoggle_plus1 CMHASHMAC.

Structure CMHASHMAC

CMHASHMAC contains all information needed for calculating message authentication codes or hashes.

Syntax

typedef struct __CMHASHMAC {

 CMULONG mflCtrl;

 CMULONG mulKeySrc;

 CMULONG mulAlgoType;

 CMULONG mulKeyExtType;

 CMBYTE mabReserved[48];

} CMHASHMAC;

 

Parameter

mflCtrl contains flags for future use.

mulKeySrc contains the selection of the key source CM_HASHMAC_SECRETDATA.

mulAlgoType contains the algorithm type: available are:

•CM_HASHMAC_SIPHASH24 or

•CM_HASHMAC_CMAC_AES128.

mulKeyExtType contains the extended type of the Secret Data PIO.

mabReserved is reserved for future purposes.

 

pvInput contains the buffer for the input to be processed.

cbInput contains the length of the buffer of pvInput in bytes.

pvResult contains the result, i.e. target buffer.

cbResult contains the size of the target buffer pvResult in bytes.
Depending on the algorithm type:

•CM_HASHMAC_CMAC_AES128 a minimum of 16 bytes.

•CM_HASHMAC_SIPHASH24 a minimum of 8 bytes.

Return

Length in bytes of the specified algorithm result.

If an error occurs, 0 is returned.
With the exception that if CMERROR_BUFFER_OVERFLOW is set, the minimum result length of the respective algorithm is returned.

Notes

•Empty messages are supported only for CmDongle Firmware versions higher than 4.10. Otherwise, the error code CMERROR_COMMANDINCOMPLETE is set.

•The maximum input size is currently 3824 bytes.

•The CM_HASHMAC_CMAC_AES128 algorithm can handle input which is not a multiple of the key length (16 bytes) only with available Firmware Version higher than 4.10. Otherwise the error code CMERROR_INTERNAL is set.

•The byte sequence of the SipHash tag in pvResult is big endian ordered.

Error Codes

CMERROR_INVALID_PARAMETER

•If pcmHASHMAC == NULL, ((pvInput == NULL && cbInput != 0) || (pvInput != NULL && cbInput == 0)).

•If pvResult == NULL and (cbResult >= 8 || cbResult >= 16).

•If key source is not known mulKeySrc == 0 or mulKeySrc > CM_HASHMAC_KSMAX.

•If algorithm is not known mulAlgoType == 0 or mulAlgoType > CM_HASHMAC_ALGMAX.

•If cbInput > UINT16_MAX (65535).

CMERROR_WRONG_HANDLE_TYPE

•If a Subsystem, Box or Firm Item handle is used.

CMERROR_WRONG_BOX_VERSION

•If the used Firmware not yet supports the feature.

CMERROR_FUNCTION_NOT_IMPLEMENTED

•In the case of CmLAN of Runtime Bridge modules.

CMERROR_FUNCTION_NOT_SUPPORTED

•For CmActLicense Firm Codes and CmActLicense Universal Firm Code container.

CMERROR_BUFFER_OVERFLOW

•If cbResult is smaller, than the respose length of the respective algoritm.