Frequently Asked Questions

Core API

• Expand all Collapse all
• Activate/start Usage Period using CodeMeter Core API URL copied to clipboard
  If you would like to start or activate the Usage Period of a license by using the CodeMeter Core-API, it is not sufficient to simply run a CmAccess2 on the corresponding license entry.
  CmCrypt2 is required for this. This is because the encryption/decryption is carried out on the CmContainer, which finally starts the Usage Period.
  
  Further information about CmCrypt2 can be found in the CodeMeter Core-API Help or in the CodeMeter API Guide.
• Checking the Firm Key in the Firm Security Box (FSB) URL copied to clipboard
  The Firm Key cannot be read directly from a Firm Security Box (FSB) or the Firm Code.
  In order to compare it between 2 FSBs, a public key of the corresponding entry can be created and compared with other public keys.
  
  These public keys must be identical for all FSBs that have the same Firm Code.
  
  To create a required public key, proceed as follows:
  1. Call core API function CmAccess2() and execute an entry access to 99:<Your Firm Code>.
  2. Create a public key with this access (handle) together with the function CmGetPublicKey() and use the Secret Data data field type 128.
  
  The above steps can also be done with CodeMeter API Guide.
  You open this tool via the system menu "Start | All Programs | CodeMeter | Tools".
• Creating random numbers using a CmDongle URL copied to clipboard
  To use the True Random Number Generator (RNG) in the CmDongle, you can use the API function CmCalculateSignature().
  This function uses the RNG of the CmDongle in the background to create a signature. You can then use the resulting signature as a seed of any random number generator on the software side.
  The CmCaluculateSignature() call requires a handle on a CmDongle or a Firm Item/License entry on a CmDongle. Furthermore, a CmAuthenticate structure is required which contains the configuration to be used for creating the signature. SerialKey and Direct are sufficient for the Ctrl field.
  More information can be found in the CodeMeter Core API help (http://localhost:22352/%24api_help/CmAPIHelp/index.html?start.htm).
• Decrement Unit Counter with CodeMeter Core API URL copied to clipboard
  To decrement the Unit Counter of a license entry, a handle to the license entry is required first. This can be achieved with the CmAccess2 function.
  With the help of the handle then an encryption uing CmCrypt2 can be accomplished. In the BaseCrypt structure it can then be specified as part of the EncryptionCodeOptions by how many units the Unit Counter should be reduced, e.g. cmBaseCrypt.EncryptionCodeOptions |= 1;
  Note: a maximum of 9999 units can be reduced at once.
  
  Additionally using the EncryptionCodeOption it can be configured that CmCrypt2:
   - makes sure that a Unit Counter is present and that it has a value > 0
   - checks if a Unit Counter is present and if it is present, that it has a value > 0
   - ignores if a Unit Counter is present at all e.g. cmBaseCrypt.EncryptionCodeOptions |= (uint) CmBaseCrypt.EncCodeOption.UnitCounterCheck;
  
  Sample code for general use of CmCrypt2 can be found in the CmCalculator sample at:
  C:\Users\Public\Documents\WIBU-SYSTEMS\SoftwareProtectionSamples.zip\C++\Special\CmCalculator\
  CCMCalculatorDlg::DoRuntimeCheck
  
  Additional information about the API functions can also be found in the CodeMeter Core API help at:
  C:\ProgramData\Microsoft\Windows\Start Menu\Programs\CodeMeter\Documentation |Core API Help
• Generic Programming Sequence URL copied to clipboard
  The Generic Programming Sequence (GPS) allows to prepare a programming sequence into which any data can be inserted at runtime.
  With this sequence any application can write data into data fields of a license without access to a Firm Security Box (FSB). This works for the following data fields:
  - Extended Protected Data
  - Hidden Data
  - Secret Data
  
  For this a tool (GenericPgmSequence.exe) exists for creating sample code for a special field of a license. This contains:
  - the required API calls of the CodeMeter Core API for the programming sequence
  to use.
  - a specific header and trailer that only works for that entry.
  Header and trailer are always specific to the combination of:
  Firm Code, Product Code, Data Field Type, Data Field Extended Type (page).
  For the calculation of the specific headers and trailers an FSB is needed once.
  You can then integrate this in your application and use it as often as you like.
  
  For preparation, you must first create the entry for which the sequence is to be created. Here it is important that the entry is programmed without dependencies.
  An example command line: cmboxpgm -qb1 -f10 -p123 -phd1:0x1234,none -ca
  This creates a Product Item 123 for Firm Code 10 with a Hidden Data field with Extended Type 1 and no dependencies.
  More details on programming licenses with CmBoxPgm can be found in the Developer's Guide: "Programming CmContainers and Licensing Management | CmBoxPgm".
  
  You can then generate the sample code. Templates next to the tool are used for this. You can specify them with /i, by default 'c++.txt' is used.
  Syntax:
  GenericPgmSequence.exe [options]
  /F<firmcode> -- FirmCode
  /P<ProductCode> -- ProductCode
  /T<ExtendedType> -- ExtendedType
  /D[E|H|S |U] -- Type of Data (<E>xtendedProtectedData, <H>iddenData, <S>ecretData, <U>serData)
  
  For Universal Firm Codes, this type of programming is supported for Runtime versions 6.50 and higher and Firmware versions 4.0 and higher.
• Open multiple handles at once with CmAccess2 URL copied to clipboard
  In certain scenarios, it may be necessary to open several handles at once. For example, if you start several threads and want to allocate one license per thread.
  
  Since CodeMeter version 6.20 it is possible to open several handles with one function call with CmAccess2(). For this you can use the following code:
  CMACCESS2 cmAcc;
  cmAcc.mflCtrl |= CM_ACCESS_USERLIMIT;
  cmAcc.mulLicenseQuantity = 5; //Number of handles to open
  cmAcc.mulUsedRuntimeVersion = CM_SET_VERSION(6, 20, 0);
  hcmse = CmAccess2(CM_ACCESS_LOCAL, &cmAcc);
  
  Please note that there will be an error "CMERROR_NO_MORE_LICENSES" if there are not enough free licenses available. Further information can be found in the CodeMeter Core API Help under CmAccess2.
• Read hardware type of the CmDongle via API URL copied to clipboard
  The information you are looking for is stored in the Extended Protected Data field 131 of the license entry 0:0.
  Enclosed you will find a code snippet (C++) that reads the information and interprets it accordingly.
  
  You can execute this code snippet by using the CmDemo C++ example from the CodeMeter Software Development Kit (Start | Programs | CodeMeter | Samples) and replacing the method MyCode() there.
  After starting the program you can select the CmContainer and then use Run MyCode to display the hardware type.
• Read Hidden Data using Core API URL copied to clipboard
  Enclosed you will find sample code for reading HiddenData, which you can apply and test in the CmDemo example.
  There you replace the function MyCode() and run the code via Run MyCode.
  
  This example code consists of 2 parts:
  
  Part 1:
  Here you first calculate the PioCoreKey for your license in an internal application in your company.
  - To calculate the "PioCoreKey", use the function "CmCalculatePioCoreKey()".
  This calculation requires access to your FSB.
  - Enter the Hidden Data Access Code of the corresponding Hiddata Data Index, which is used to encrypt the data.
  - Now use the calculated PioCoreKey to calculate a key pair of PioEncryptionKey and PioDataKey.
  For the PioEncryptionKey, you can use random values of 16 bytes or determine a value yourself.
  - With the function "CmGetPioDataKey ()" you then get the PioDataKey with the specified PioCoreKey and PioEncryptionKey.
  
  Since only you have a Firm Security Box (FSB) and since you should not release the PioCoreKey, all this happens in an internal application that you do not give to your customer.
  
  Part 2
  This part now happens completely in your application that you send to the customer.
  - Here you use the previously created PioEncryptionKey and PioDataKey key pairs to read the Hidden Data.
  - First you use the function CmGetSecureData() and the PioEncryptionKey to retrieve the Hidden Data from the CmContainer.
  - Then you only have to decrypt this data with the function CmDecryptPioData() and the PioDataKey.
• Reading the COLI of a license using CodeMeter Core API URL copied to clipboard
  The COLI is a so-called "Pseudo Product Item Option (PIO)". This means that this PIO does not have its own place in the structure of a license, but is encoded in data fields of the license.
  The COLI is programmed as an Extended Protected Data field with Extended Type 250. This means that to read out the COLIs the Extended Protected Data field must be read out with Extended Type 250. This is coded as a UTF-8 string.
  
  An example of how this can be done can be found in the CmDemo sample that is installed with the Windows CodeMeter SDK.
  You can find the sample at: C:\Users\Public\Documents\WIBU-SYSTEMS\SoftwareProtectionSamples.zip\<Programming Language>\Special\CmDemo.
  Please take a closer look at the method "ListProductItem".
• Using CodeMeter API in 64-bit Delphi applications URL copied to clipboard
  In order to use the CodeMeter API in a 64-bit based Delphi application, please follow the following steps:
  1. Copy the CodeMeter.pas from C:\Program Files (x86)\CodeMeter\DevKit\include next to your 64-bit project
  2. Include the CodeMeter.pas in your project and open the CodeMeter.pas
  3. Edit line 64 and change the constant "LIB" from WibuCm32.dll to WibuCm64.dll
  
  You are now able to use all the CodeMeter API functions in your 64-bit application. Please note that the Programming API HipApi is not available for 64-bit applications.