CmEmbedded_4c_transp CmGetPublicKey

Description

CmGetPublicKey returns a public key from the CmContainer. The CmContainer usually stores private keys only. With this request the CmContainer calculates the corresponding public key using Elliptic Curve Cryptography (ECC).

  • C, C++

Syntax

int CMAPIENTRY CmGetPublicKey(HCMSysEntry hcmse, CMAUTHENTICATE *pcmAuth, CMBYTE *pbPubKey, CMUINT cbPubKey);

Parameter

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

pcmAuth contains the specification of the desired public key (see structure hmtoggle_plus1 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:

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

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

nav_open CM_AUTH_SERIALKEY specifies that the signature calculation is done with the Serial Key.

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

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

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

nav_open 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:

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

nav_open 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.

nav_open 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.
Plese note that using CM_AUTH_EXTENDED2 requires at least hardware version 2.03.

nav_open 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(2) 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(2) 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.

 

pbPubKey contains the buffer for the public key.

cbPubKey contains the length of the pbPubKey buffer.

Return

The return value is TRUE, if the public key is returned, FALSE if not.

Notes

The pcmAuth structure has to be almost completely empty. The only value that has to be set is mflCtrl which has to be set to one of the following values: CM_AUTH_HIDDENDATA, CM_AUTH_SECRETDATA, CM_AUTH_SERIALKEY.

The value CM_AUTH_FIRMKEY is invalid here as this function cannot directly calculate the public key for the Firm Key. To calculate the public key for the Firm Key for Firm Item X calculate the public key for FSB entry 99:x Secret Data 128.

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