CmEmbedded_4c_transp CmGetSecureData

Description

CmGetSecureData reads encrypted Hidden Data from a CmContainer entry. The retrieved encrypted data has to be decrypted individually.

  • C, C++

Syntax

int CMAPIENTRY CmGetSecureData(HCMSysEntry hcmse, CMSECUREDATA *pcmSecureData, CMENTRYDATA *pcmEntryData);

Parameter

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

pcmSecureData contains a hmtoggle_plus1 CMSECUREDATA structure.

Structure CMSECUREDATA

CMSECUREDATA stores all needed parameters for an encrypted reading of a PIO.

Syntax

typedef struct __CMSECUREDATA {

CMBASECRYPT mcmBaseCrypt;

CMUSHORT musPioType;

CMUSHORT musExtType;

CMBYTE mabPioEncryptionKey[CM_BLOCK_SIZE];

CMULONG mulReserve;

} CMSECUREDATA;

Parameter

mcmBaseCrypt contains all needed parameters for an encryption (see structure hmtoggle_plus1 CMBASECRYPT for parameter settings for data to be encrypted.

Structure CMBASECRYPT

CMBASECRYPT stores all needed parameters needed for every possible en- or decryption.

Syntax

typedef struct __CMBASECRYPT {

CMULONG mflCtrl;

CMULONG mulKeyExtType;

CMULONG mulEncryptionCode;

CMULONG mulEncryptionCodeOptions;

CMULONG mulFeatureCode;

CMULONG mulCrc;

} CMBASECRYPT;

Parameter

mflCtrl contains commands and flags influencing the en- or decryption. The parameter can use the following flags:

Used Key:

nav_open CM_CRYPT_HIDDENDATA specifies that the encryption key is stored in a Hidden Data of a Product Item. The Key Source must also be specified here.

Used Encryption Algorithm:

nav_open CM_CRYPT_AES specifies that the Advanced Encryption Standard (AES) algorithm is used for encryption. The key CM_CRYPT_HIDDENDATA. The encryption will be affected by other parameters such as Firm Code, Product Code, Encryption Code etc.

nav_open CM_CRYPT_ECIES specifies that the Elliptic Curve Integrated Encryption Scheme (ECIES) algorithm is used for encryption. This flag is only allowed for direct encryption (see Encryption Modes).

nav_open CM_CRYPT_ECIES_STD specifies that the Elliptic Curve Integrated Encryption Scheme (ECIES) algorithm is used for encryption. This option executes the standard ECIES. This flag only works with direct encryption. Encryption only works with simulated encryption (CmCryptSim). The length of the buffer must be at least 64 bytes (CM_PUBLIC_KEY_LEN) larger than the input sequence to add the public key after the encrypted sequence. Decryption only works with real decryption (CmCrypt). Though the returned length is 64 bytes smaller than the input sequence. This flag is only valid for direct encryption (see Encryption Modes)

nav_open CM_CRYPT_AES_DIRECT specifies that the direct Advanced Encryption Standard (AES) algorithm is used for encryption without hash calculation. The length of the buffer must be at least 16 bytes. The key to use is CM_CRYPT_HIDDENDATA. This algorithm is compatible to standard AES. Required CmContainer Firmware version: 1.10.

CRC calculation:

The algorithm CRC-32 is used to calculate the CRC checksum of the data.

nav_open CM_CRYPT_CHKCRC specifies that the CRC value stored in mulCrc should be checked using the CRC of the current operation.

nav_open CM_CRYPT_CALCCRC specifies that the CRC of the current operation should be calculated and stored in mulCrc.

mulKeyExtType specifies the key source, if the encryption is done with a Hidden Data.

mulEncryptionCode contains the Encryption Code set by the user.

mulEncryptionCodeOptions contains one or more of the following flags:

nav_open CM_CRYPT_RES1MASK reserved for future use.

nav_open CM_CRYPT_UCMASK specifies all flags for the Unit Counter options.

nav_open CM_CRYPT_UCCHECK specifies that the Unit Counter is checked and reduced, if available as Product Item Option.

nav_open CM_CRYPT_UCIGNORE specifies that the Unit Counter is neither checked nor reduced, independent of its availability as Product Item Option.

nav_open CM_CRYPT_UCREQUIRED specifies that a Unit Counter is checked and reduced and must be available as Product Item Option.

nav_open CM_CRYPT_ATMASK specifies all flags for the Activation Time.

nav_open CM_CRYPT_ATCHECK specifies that the Activation Time is checked, if available as Product Item Option.

nav_open CM_CRYPT_ATIGNORE specifies that the Activation Time is not checked, independent of its availability as Product Item Option.

nav_open CM_CRYPT_ATREQUIRED specifies that a Activation Time is checked and must be available as Product Item Option.

nav_open CM_CRYPT_ETMASK specifies all flags for the Expiration Time options.

nav_open CM_CRYPT_ETCHECK specifies that Expiration Time or Usage Period are checked, if available as Product Item Option.

nav_open CM_CRYPT_ETIGNORE specifies that Expiration Time and Usage Period are not checked, independent of its availability as Product Item Option.

nav_open CM_CRYPT_ETREQUIRED specifies that Expiration Time or Usage Period are checked and one of them must be available as Product Item Option.

nav_open CM_CRYPT_CERTTIME specifies that the Certified Box Clock (CBC) has to be updated by a Certified Time Stamp (CTS) since the CmDongle has received power. This option is only evaluated, if an Expiration Time Product Item Option is available.

nav_open CM_CRYPT_FACDECREMENT specifies that the Access Counter is reduced by 1.

nav_open CM_CRYPT_TOPLAINONLY specifies that the CmContainer can execute only the decryption but not the encryption variant. This flag can only be used in combination with the CmCrypt flag CM_CRYPT_DIRECT_DEC. The corresponding encryption has to be done by using CmCryptSim.

nav_open CM_CRYPT_RES2MASK reserved for future use.

nav_open CM_CRYPT_SAMASK specifies all flags for network access. These bits affect the encryption.

information_weiss_klein26

Please make sure that these flags correspond to the access modes flags you have set the in CmAccess2.

nav_open CM_CRYPT_SAEXCLUSIVE specifies that the current access is done using Exclusive Mode.

nav_open CM_CRYPT_SAUNLIMITED specifies that the current access is done using No User Limit.

nav_open CM_CRYPT_SAUSERLIMIT specifies that the current access is done using User Limit.

nav_open CM_CRYPT_SASTATIONSHARE specifies that the current access is done using Stationshare Mode.

nav_open CM_CRYPT_RES3MASK reserved for future use.

nav_open CM_CRYPT_UCDELTAMASK contains the mask to specify the delta value to reduce the Unit Counter value during encryption. The value is limited to the range of 0 to 9999, values between 10000 and 16383 are reserved for future use.

mulFeatureCode specifies the Feature Code mapping for the existing Feature Map. The operation fails, if the Feature Code contains bits which do not exist in the Feature Map.

mulCrc contains the CRC value of the current operation. It depends on the CM_CRYPT_CALCCRC or CM_CRYPT_CHKCRC flags, if this value is set or checked.

 

musExtType contains the extended type (ID) of the PIO to read.

musPioType contains the type of the PIO to read out in an encrypted way.

nav_open CM_GF_HIDDENDATA specifies that the PIO to read is a Hidden Data.

mabPioEncryptionKey[CM_BLOCK_SIZE] contains the PIOEK (Product Item Option Encryption Key).

mulReserve is reserved for future purposes.

 

pcmEntryData contains a hmtoggle_plus1 CMENTRYDATA structure receiving the encrypted data.

Structure CMENTRYDATA

CMENTRYDATA contains a dynamic added data of a Product Item with all its properties.

Syntax

typedef struct __CMENTRYDATA {

CMULONG mflCtrl;

CMULONG mflDependency;

CMUINT mcbData;

CMBYTE mabData[2 * CM_MAX_STRING_LEN];

} CMENTRYDATA;

Parameter

mflCtrl specifies the type of the dynamic added entry. It can contain the following flag:

nav_open CM_GF_HIDDENDATA specifies that the Product Item contains one or more HiddenData Data.

For the entry type Hidden Data the index of this data type is or'ed in the upper two bytes. See remarks for a sample.

mflDependency contains the dependency of the dynamic added entry. It can be have one or more of the following flags:

nav_open CM_GF_DATA specifies that the parameter depends on the contents of the data of the Firm Item.

nav_open CM_GF_FUC specifies that the parameter depends on the Firm Update Counter of the Firm Item.

nav_open CM_GF_SERIAL specifies that the parameter depends on the Serial Number of the CmContainer.

mcbData contains the length of mabData, for text entries (CM_GF_TEXT) the number of characters, for all other types the number of stored bytes.

mabData[2 * CM_MAX_STRING_LEN] contains the data of the dynamic added entry with the length stored in mcbData. For text entries (CM_GF_TEXT) the byte array contains an UCS2-LE encoded null-terminated string.

Notes

To check the mflCtrl you can use the CM_GF_PIO_MASK to retrieve only the data type flag, e.g. mflCtrl & CM_GF_PIO_MASK. To retrieve the index of Hidden Data you need to extract the upper two bytes of mflCtrl, e.g. by mflCtrl >> 16.

For an easier conversion of mabData it may be helpful to use CmConvertString().

 

Return

The return value contains the number of bytes containing the plain data returned encrypted in CMENTRYDATA::mabData. If an error occurred, 0 is returned.

Notes

For Hidden Data, the Hidden Data Access Code (HDAC) must specified and match the stored value.