CmCalculateSignature

<< Click here to display Table of Contents >> Navigation: Functions / Methods > Authentication operations:

Contents

Description

CmCalculateSignature() calculates a signature using the ECDSA algorithm of the given digest directly via a CmContainer entry.

Syntax

int CMAPIENTRY CmCalculateSignature(HCMSysEntry hcmse, CMAUTHENTICATE *pcmAuth, CMBYTE *pbSignature, CMUINT cbSignature);

The digest is available as mabDigest of the structure CMAUTHENTICATE.

Structure CMAUTHENTICATE

CMAUTHENTICATE contains all information needed for an authentication process.

Syntax

typedef struct __CMAUTHENTICATE {

CMULONG mflCtrl;
CMULONG mulKeyExtType;
CMULONG mulFirmCode;
CMULONG mulProductCode;
CMULONG mulEncryptionCodeOptions;
CMULONG mulFeatureCode;
CMBOXINFO mcmBoxInfo;
CMBYTE mabDigest[CM_DIGEST_LEN];

} CMAUTHENTICATE;

Parameter

mflCtrl contains one of the following commands:

CM_AUTH_FIRMKEY specifies that the signature calculation is done with the Firm Key.

CM_AUTH_HIDDENDATA specifies that the signature calculation is done with a Hidden Data field.

CM_AUTH_SECRETDATA specifies that the signature calculation is done with a Secret Data field.

CM_AUTH_SERIALKEY specifies that the signature calculation is done with the SerialKey.

CM_AUTH_BOXKEY specifies that the signature calculation is done with the Box Key.

CM_AUTH_PISK specifies that the signature calculation is done with the PISK (Product Item Security Key).

CM_AUTH_KSMASK can be used to mask bits used for specifying the key source.

CM_AUTH_AMMASK can be used to mask bits used for specifying the authentication mode.

This commands can be or'ed with one of the following flags:

CM_AUTH_DIRECT uses the specified digest directly as input of the ECDSA algorithm.

CM_AUTH_EXTENDED defines that the specified Encryption Code Options and Feature Code influence the use of the Product Item and influences the signature calculation.

CM_AUTH_EXTENDED2 improves the definition that the specified Encryption Code Options and Feature Code influence the use of the Product Item and influences the signature calculation .
The flag has been introduced with CodeMeter Version 5.10. Please note that using CM_AUTH_EXTENDED2 requires at least hardware version 2.03.

CM_AUTH_SERIAL defines that the specified Encryption Code Options influence the use of the Product Item and influences together with the Serial Number of the CmContainer the signature calculation.

mulKeyExtType contains the extended type of the Hidden Data or Secret Data PIO, if in mflCtrl CM_AUTH_HIDDENDATA or CM_AUTH_SECRETDATA is specified. Otherwise this member must be set to 0.

mulFirmCode contains the Firm Code used for the authentication process.

mulProductCode contains the Product Code used for the authentication process.

mulEncryptionCodeOptions contains the Encryption Code Options, this are the higher 32 bits of the Encryption Code. This value is only used, if mflCtrl has set the CM_AUTH_EXTENDED, CM_AUTH_EXTENDED, CM_AUTH_EXTENDED2 or CM_AUTH_SERIAL option. Otherwise it must be set to 0.

mulFeatureCode contains the used Feature Code, which must match the used Feature Map. This value is only used, if mflCtrl has set the CM_AUTH_EXTENDED, CM_AUTH_EXTENDED, CM_AUTH_EXTENDED2 option. Otherwise it must be set to 0.

mcmBoxInfo contains the CmContainer information used for the authentication process.

mabDigest contains the 32-byte res. 256-bit digest which is signed.

hcmse contains a handle opened with CmAccess2 (Entry Access).

pcmAuth contains all information needed for the authentication process (see structure CMAUTHENTICATE.

pbSignature contains the buffer for the signature.

cbSignature contains the length of the buffer of pbSignature. The length has to be CM_PUBLIC_KEY_LEN which is 64.

Return

True (1), if the signature was calculated successful. If an error occurs, 0 is returned and an error code is set.

Notes

•The hash value used for the signature must always be set into pcmAuth->mabDigest.

•The value pcmAuth->mflCtrl has to be a combination of signature method and key source. The values are or'ed together.

•Signature method is one of CM_AUTH_DIRECT, CM_AUTH_EXTENDED, CM_AUTH_EXTENDED2 or CM_AUTH_SERIAL.

•Key source is one of CM_AUTH_HIDDENDATA, CM_AUTH_SECRETDATA, CM_AUTH_SERIALKEY.

•In the case of Hidden Data or Secret Data, the extended type must be set as pcmAuth->mulKeyExtType. Otherwise this value should be 0.

•CM_AUTH_DIRECT: All other values are ignored and should be set to 0.

•CM_AUTH_EXTENDED(2): pcmAuth->mulEncryptionCodeOptions has to have the same value as for CmValidateSignature. pcmAuth->mulFeatureCode can be set to a specific value. The value will be integrated into the signature but the signature will only be calculated, if the requested Feature Code conforms with the current Feature Map. The signature incorporates the serial number of the signing CodeMeter and the Firm Code / Product Code values used for CmAccess2. These values have to be remembered to correctly verify the signature later using CmValidateSignature.
The flag has been introduced with CodeMeter Version 5.10. Please note that using CM_AUTH_EXTENDED2 requires at least hardware version 2.03.

•CM_AUTH_SERIAL: pcmAuth->mulEncryptionCodeOptions has to have the same value as for CmValidateSignature. All other values should be set to 0. The signature incorporates the serial number of the signing CodeMeter and the Firm Code / Product Code values used for CmAccess2. These values have to be remembered to correctly verify the signature later using CmValidateSignature.

•CM_AUTH_PISK (Product Item Secret Key) has been introduced with CodeMeter Version 6.0 (License Transfer).