CmEmbedded_4c_transp CmCrypt2

Description

CmCrypt2 encrypts or decrypts data using direct or indirect encryption (see Encryption Modes) via a CmContainer entry.

  • C, C++

Syntax

int CMAPIENTRY CmCrypt2(HCMSysEntry hcmse, CMULONG flCtrl, CMCRYPT2 *pcmCrypt, void* pvDest, CMUINT cbDest)

Parameter

hcmse contains a handle opened by CmAccess2. Access Mode must be Entry Access to the Firm Code:Product Code entry used for en-/decryption. For software encryption (CM_CRYPT_AES_ENC_CBC_DIRECT or CM_CRYPT_AES_DEC_CBC_DIRECT) this has to be NULL.

flCtrl contains the encryption or decryption command. Following commands are supported:

nav_open CM_CRYPT_DIRECT_ENC executes the direct symmetric encryption via a CmContainer entry. The length of bytes to encrypt must be exactly 16 bytes (for CM_CRYPT_AES) or between 0 and 32 bytes (for CM_CRYPT_ECIES and CM_CRYPT_ECIES_STD) - see structure hmtoggle_plus1 CMBASECRYPT2.

Structure CMBASECRYPT2

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

Syntax

typedef struct __CMBASECRYPT2 {

CMULONG mflCtrl;

CMULONG mulKeyExtType;

CMULONG mulEncryptionCode;

CMULONG mulEncryptionCodeOptions;

CMULONG mulFeatureCode;

CMTIME mcmReleaseDate;

CMULONG mulCrc;

} CMBASECRYPT2;

Parameter

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

Used Key:

nav_open CM_CRYPT_FIRMKEY specifies that the encryption key is stored in the Firm Key of a Firm Item.

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.

nav_open CM_CRYPT_SECRETDATA specifies that the encryption key is stored in a Secret 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 may be CM_CRYPT_FIRMKEY, CM_CRYPT_HIDDENDATA or CM_CRYPT_SECRETDATA. 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 (CmCrypt2). 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 may be CM_CRYPT_HIDDENDATA or CM_CRYPT_SECRETDATA. CM_CRYPT_FIRMKEY is not implemented. This algorithm is compatible to standard AES. Required CmContainer Firmware version: 1.10.

nav_open CM_CRYPT_RSA specifies that the standard RSA algorithm is used. The length of the buffer must be at least 128 bytes (CM_RSA1024_KEY_LEN). The keys must locate in a Secret Data entry of a Firm Code or Product Code:

•d (private key) in SecretData ExtType 130

•p (secret prime) in SecretData ExtType 131

•q (secret prime) in SecretData ExtType 132

Requirements:

•For d, p, and q exactly these ExtTypes must be programmed.

•For security reasons these SecretData types must be programmed in this exact sequence. First ExtType 130, then 131, and finally 132. If programmed in another order, the respective preceeding SecretData fields are overwritten.

•All three numbers must be specified using Little Endian.
Please note that some tools, for example, openssl create keys using Big Endian.

CM_CRYPT_RSA requires at least a CmContainer Firmware version 1.11. Then key lengths up to 1024 bytes are supported. Firmware version 2.02 and higher supports key lengths up to 2048 bytes.

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 or a Secret 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_MPREQUIRED specifies that a Maintenance Period is checked and must be available as Product Item Option.

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 CmCrypt2 flag CM_CRYPT_DIRECT_DEC. The corresponding encryption has to be done by using CmCryptSim2.

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.

mcmReleaseDate specifies the Release Date in a hmtoggle_plus1 CMTIME structure that has to map to the existing Maintenance Period. The operation fails, if the Release Date is not in the Maintenance Period.

Structure CMTIME

CMTIME sets or gets the time to or from a CmContainer.

Syntax

typedef struct __CMTIME {

CMUSHORT musYear;

CMUSHORT musMonth;

CMUSHORT musDay;

CMUSHORT musHours;

CMUSHORT musMinutes;

CMUSHORT musSeconds;

CMULONG mulSecondsSince01_01_2000;

} CMTIME;

Parameter

musYear specifies the value of the year (e.g. 2003).

musMonth specifies the value of the month (1..12).

musDay specifies the value of the day (1..31).

musHours specifies the value of the hours (0..23).

musMinutes specifies the value of the minutes (0..59).

musSeconds specifies the value of the seconds (0..59).

mulSecondsSince01_01_2000 specifies the time in seconds since 01/01/2000.

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.

 

nav_open CM_CRYPT_DIRECT_DEC executes the direct symmetric decryption via a CmContainer entry. The length of bytes to decrypt must be exactly 16 bytes (for CM_CRYPT_AES) or between 0 and 32 bytes (for CM_CRYPT_ECIES and CM_CRYPT_ECIES_STD) - see CMBASECRYPT2.

information_weiss_klein26

Wibu-Systems recommends this mode since CBC is the most commonly used mode of operation.

Although CodeMeter supports also other older cryptographic modes. However, their use is not recommended.

For more information see the technical guideline TR-02102-1 "Cryptographic Mechanisms: Recommendations and Key Lengths" (courtesy translation) edited by the German Federal Office for Information Security, BSI (Bundesamt für Sicherheit in der Informationstechnik) (BSI).

nav_open CM_CRYPT_AES_ENC_CBC executes the indirect encryption using the AES block cipher algorithm with CBC.

By default, the method CTS is used. CTS stands for ciphertext stealing, i.e. swapping the final two ciphertext blocks, also in the case that cbDest is a multiple of the blocksize.
Moreover, CTS allows unpadded data, that has a length not a multiple of the block site (16 bytes), to be encrypted to the same length of the cipher text.

information_weiss_klein26

cbDest must always be equal to or larger than 16 bytes. The initialization vector (IV) is never stolen.

If cbDest equals 16 bytes, the encryption results corresponds to the encryption using standard AES CBC without CTS.

If cbDest equals 16 bytes and the initialization vector (IV) equals a value of 0, the encryption result corresponds to ECB.

nav_open CM_CRYPT_AES_DEC_CBC executes the indirect decryption using the AES block cipher algorithm with CBC.

By default, the method CTS is used. CTS stands for ciphertext stealing, i.e. swapping the final two ciphertext blocks, also in the case that cbDest is a multiple of the blocksize.
Moreover, CTS allows unpadded data, that has a length not a multiple of the block site (16 bytes), to be encrypted to the same length of the cipher text.

information_weiss_klein26

cbDest must always be equal to or larger than 16 bytes. The initialization vector (IV) is never stolen.

If cbDest equals 16 bytes, the encryption results corresponds to the encryption using standard AES CBC without CTS.

If cbDest equals 16 bytes and the initialization vector (IV) equals a value of 0, the encryption result corresponds to ECB.

nav_open CM_CRYPT_AES_ENC_CBC_DIRECT executes the encryption using the original AES block cipher algorithm with CBC.

By default, the method CTS is used. CTS stands for ciphertext stealing, i.e. swapping the final two ciphertext blocks, also in the case that cbDest is a multiple of the blocksize.
Moreover, CTS allows unpadded data, that has a length not a multiple of the block site (16 bytes), to be encrypted to the same length of the cipher text.

information_weiss_klein26

cbDest must always be equal to or larger than 16 bytes. The initialization vector (IV) is never stolen.

If cbDest equals 16 bytes, the encryption results corresponds to the encryption using standard AES CBC without CTS.

If cbDest equals 16 bytes and the initialization vector (IV) equals a value of 0, the encryption result corresponds to ECB.

It does not use any CodeMeter license, therefore use NULL for hcmse. The AES key has to be placed in mabDirectAesKey, the initialization vector in mabInitKey - both see structure hmtoggle_plus1 CMCRYPT2).

Structure CMCRYPT2

CMCRYPT2 contains all needed parameters for an encryption with a CmContainer using CmCrypt2

Syntax

typedef struct __CMCRYPT2 {

CMBASECRYPT2 mcmBaseCrypt;

CMBYTE mabDirectAesKey[CM_BLOCK_SIZE];

CMBYTE mabInitKey[CM_BLOCK_SIZE];

CMULONG maulReserved[8]

} CMCRYPT2;

Parameter

mcmBaseCrypt contains all needed parameters for an encryption (see CMBASECRYPT2).

mabDirectAesKey contains the AES key for an encryption/decryption without CmContainer using original AES. This is only used for CmCrypt2 with the flags CM_CRYPT_AES_ENC_CBC_DIRECT or CM_CRYPT_AES_DEC_CBC_DIRECT (see also Encryption Modes).

mabInitKey contains the key for the indirect encryption (see Encryption Modes). For an encryption/decryption without hardware using CmCrypt2 with the flags CM_CRYPT_AES_ENC_CBC_DIRECT or CM_CRYPT_AES_DEC_CBC_DIRECT use this member to set the initialization vector (IV).

 

nav_open CM_CRYPT_AES_DEC_CBC_DIRECT executes the decryption using the original AES block cipher algorithm with CBC.

By default, the method CTS is used. CTS stands for ciphertext stealing, i.e. swapping the final two ciphertext blocks, also in the case that cbDest is a multiple of the blocksize.
Moreover, CTS allows unpadded data, that has a length not a multiple of the block site (16 bytes), to be encrypted to the same length of the cipher text.

information_weiss_klein26

cbDest must always be equal to or larger than 16 bytes. The initialization vector (IV) is never stolen.

If cbDest equals 16 bytes, the encryption results corresponds to the encryption using standard AES CBC without CTS.

If cbDest equals 16 bytes and the initialization vector (IV) equals a value of 0, the encryption result corresponds to ECB.

It does not use any CodeMeter license, therefore use NULL for hcmse. The AES key has to be placed in mabDirectAesKey, the initialization vector in mabInitKey - both see structure hmtoggle_plus1 CMCRYPT2).

Structure CMCRYPT2

CMCRYPT2 contains all needed parameters for an encryption with a CmContainer using CmCrypt2

Syntax

typedef struct __CMCRYPT2 {

CMBASECRYPT2 mcmBaseCrypt;

CMBYTE mabDirectAesKey[CM_BLOCK_SIZE];

CMBYTE mabInitKey[CM_BLOCK_SIZE];

CMULONG maulReserved[8]

} CMCRYPT2;

Parameter

mcmBaseCrypt contains all needed parameters for an encryption (see CMBASECRYPT2).

mabDirectAesKey contains the AES key for an encryption/decryption without CmContainer using original AES. This is only used for CmCrypt2 with the flags CM_CRYPT_AES_ENC_CBC_DIRECT or CM_CRYPT_AES_DEC_CBC_DIRECT (see also Encryption Modes).

mabInitKey contains the key for the indirect encryption (see Encryption Modes). For an encryption/decryption without hardware using CmCrypt2 with the flags CM_CRYPT_AES_ENC_CBC_DIRECT or CM_CRYPT_AES_DEC_CBC_DIRECT use this member to set the initialization vector (IV).

 

pcmCrypt sets some needed data for the en-/decryption process (see CMCRYPT2).

pvDest contains the data to en-/decrypt.

cbDest contains the number of bytes to en-/decrypt stored in pvDest.  

Return

This function returns the number of en-/decrypted bytes. If an error occurred, 0 will be returned.

Notes

CmCrypt2() is supported since CodeMeter Version 4.30.

Crypt sets some needed data for the en-/decryption process (see CmCrypt2).

Dest contains the data to encrypt or decrypt.

Return

This function returns true. If an error occurred, false will be returned.

Notes

CmCrypt2() is supported since CodeMeter Version 4.30.