Häufig gestellte Fragen
Teilen:
Core API
- Bei der COLI handelt es sich um eine sogenannten "Pseudo Product Item Option (PIO)". Dies bedeutet, dass diese PIO keinen eigenen Platz in der Struktur einer Lizenz hat, sondern in Datenfelder der Lizenz codiert ist.
Die COLI wird programmiert als Extended Protected Data-Feld mit dem Extended Type 250. Dies bedeutet, zum Auslesen der COLIs muss das Extended Protected Data-Feld mit Extended Type 250 ausgelesen werden. Dieser ist als UTF-8 String kodiert.
Ein Beispiel, wie dies getan werden kann, finden Sie im CmDemo-Sample, dass mit dem Windows CodeMeter SDK mitinstalliert wird.
Sie finden das Sample unter: C:\Users\Public\Documents\WIBU-SYSTEMS\SoftwareProtectionSamples.zip\<Programmiersprache>\Special\CmDemo.
Bitte schauen Sie sich die Methode "ListProductItem" genauer an. - Um in einer Delphi 64-Bit-Anwendung die CodeMeter API zuverwenden sind die folgenden Schritte notwendig:
1. Kopieren der Datei CodeMeter.pas von C:\Program Files (x86)\CodeMeter\DevKit\include zu Ihrem Projekt.
2. Einbinden der CodeMeter.pas in Ihr Projekt, nachdem Sie die 64-Bit-Plattform als Zielplattform ausgewählt haben .
3. Ändern in Zeile 64 der Datei CodeMeter.pas die Konstante "LIB" (= WibuCm32.dll) zu WibuCm64.dll
Anschließend sind Sie in der Lage, alle Funktionen des CodeMeter API-Interfaces in Ihrer eigenen 64-Bit-Anwendung zu verwenden.
Bitte beachten Sie, dass die HipApi-Programmier-API nicht für 64-Bit zur Verfügung steht. - Die Generic Programming Sequence ermöglicht, eine Programmiersequenz vorzubereiten, in die zur Laufzeit beliebige Daten eingefügt werden können.
Mit dieser kann dann eine beliebige Anwendung ohne Zugriff auf eine Firm Security Box (FSB) Daten in Datenfelder einer Lizenz schreiben. Dies funktioniert für die folgenden Datenfelder:
- Extended Protected Data
- Hidden Data
- Secret Data
Hierfür gibt es ein Tool (GenericPgmSequence.exe), mit dem Sie für ein spezielles Feld einer Lizenz Beispiel-Code erstellen können. Dieser enthält:
- die benötigen API-Calls der CodeMeter Core API um die Programmiersequenz
zu verwenden.
- einen spezifischen Header und Trailer, der nur für genau diesen Eintrag funktioniert.
Header und Trailer sind immer spezifisch für die Kombination aus:
Firm Code, Product Code, Datenfeld Type, Datenfeld Extended Type (page).
Für das Berechnen der spezifischen Header und Trailer wird einmalig eine FSB benötigt.
Anschließend können Sie diese in ihrer Anwendung einbauen und beliebig oft verwenden.
Zur Vorbereitung muss zuerst der Eintrag angelegt werden, für den die Sequenz erzeugt werden soll. Hier ist wichtig, dass der Eintrag ohne Abhängigkeiten programmiert wird.
Eine Beispiel-Kommandozeile: cmboxpgm -qb1 -f10 -p123 -phd1:0x1234,none -ca
Hiermit wird ein Product Item 123 für Firm Code 10 erzeugt mit einem Hidden Data-Datenfeld mit Extended Type 1 und keinen Abhängigkeiten.
Mehr Details zum Programmieren von Lizenzen mit CmBoxPgm finden Sie im Entwicklerhandbuch unter: "Programmierung von CmContainern und Lizenzierungsverwaltung | CmBoxPgm".
Anschließend können Sie den Beispiel-Code erzeugen. Hierfür werden Templates benutzt, die neben dem Tool liegen. Sie können diese mit /i spezifizieren, standardmäßig wird 'c++.txt' verwendet.
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)
Für Universal Firm Codes wird diese Art der Programmierung erst ab Runtime Version 6.50 und Firmware Version 4.0 unterstützt. - Die gesuchte Information ist im Extended Protected Data-Feld 131 des Lizenzeintrags 0:0 hinterlegt.
Anbei finden Sie ein Code-Schipsel (C++), das die Information ausliest und entsprechend interpretiert.
Sie können diesen Code-Schnipsel ausführen, in dem Sie das CmDemo C++-Beispiel aus dem CodeMeter Software Development Kit (Start | Programme | CodeMeter | Samples) verwenden und dort die Methode MyCode() ersetzen.
Nach dem Starten des Programmes können Sie den CmContainer auswählen und sich dann über Run MyCode dazu den Hardware-Typ ausgeben lassen. - Anbei finden Sie Beispiel-Code zum Auslesen von HiddenData, den Sie in unserem CmDemo-Beispiel ausprobieren können.
Dort ersetzen Sie die Funktion MyCode() und führen dann den Code über Run MyCode.
Dieser Beispiel-Code besteht aus 2 Teilen:
Teil 1:
Hier berechnen Sie zunächst in einer internen Anwendung in Ihrem Unternehmen den PioCoreKey für Ihre Lizenz.
- Um den "PioCoreKey" zu berechnen, verwenden Sie die Funktion "CmCalculatePioCoreKey()".
Für diese Berechnung wird ein Zugriff auf Ihren FSB benötigt.
- Geben Sie dabei den Hidden Data Access Code des entsprechenden Hidden Data Index an, über den die Daten verschlüsselt sind.
- Jetzt verwenden Sie den berechneten PioCoreKey, um ein Schlüsselpaar von PioEncryptionKey und PioDataKey zu berechnen.
Für den PioEncryptionKey können Sie zufällige Werte von 16 Bytes verwenden oder selbst einen Wert bestimmen.
- Mit der Funktion "CmGetPioDataKey ()" erhalten Sie dann mit angegebenem PioCoreKey und PioEncryptionKey den PioDataKey.
Da nur Sie eine Firm Security Box (FSB) haben und da Sie den PioCoreKey nicht herausgeben sollten, passiert dies bislang alles in einer internen Anwendung, die Sie nicht Ihrem Kunden geben.
Teil 2:
Dieser Teil passiert nun vollständig in Ihrer Anwendung, die Sie zum Kunden schicken.
- Hier verwenden Sie nun die zuvor erstellen PioEncryptionKey und PioDataKey-Schlüsselpaare zum Auslesen der Hidden Data.
- Zunächst holen Sie mit der Funktion CmGetSecureData() und dem PioEncryptionKey die HiddenData aus dem CmContainer.
- Anschließend müssen Sie diese Daten nur noch mit der Funktion CmDecryptPioData() und dem PioDataKey entschlüsseln. - In bestimmten Szenarien kann es notwendig sein, mehrere Handles auf einmal zu öffnen. Z.B. wenn man mehrere Threads startet und pro Thread eine Lizenz belegt werden soll.
Seit CodeMeter-Version 6.20 ist es möglich, mit CmAccess2() mehrere Handles mit einem Funktionsaufruf zu öffnen. Dafür können Sie z.B. folgenden Code verwenden:
CMACCESS2 cmAcc;
cmAcc.mflCtrl |= CM_ACCESS_USERLIMIT;
cmAcc.mulLicenseQuantity = 5; //Anzahl der zu öffnenden Handles
cmAcc.mulUsedRuntimeVersion = CM_SET_VERSION(6, 20, 0);
hcmse = CmAccess2(CM_ACCESS_LOCAL, &cmAcc);
Bitte beachten Sie dabei, dass es zu einem Fehler "CMERROR_NO_MORE_LICENSES" kommt, wenn nicht genügend freie Lizenzen zu Verfügung stehen. Weitere Informationen dazu finden Sie in der CodeMeter Kern-API Hilfe unter CmAccess2 - Möchte man den Nutzungszeitraum einer Lizenz über die Verwendung des CodeMeter Core-API anbrechen/aktivieren, so reicht es nicht aus, lediglich ein CmAccess2 auf den entsprechenden Lizenzeintrag durchzuführen.
Hierfür wird CmCrypt2 benötigt. Denn damit wird eine Ver/Entschlüsselung auf dem CmContainer durchgeführt, die dann schlussendlich den Nutzungszeitraum anbricht.
Weitere Informationen zu CmCrypt2 können Sie in der CodeMeter Core-API Hilfe bzw. im CodeMeter API Guide finden. - Der Firm Key kann nicht direkt aus einer Firm Security Box (FSB) oder dem Firm Code ausgelesen werden.
Um diesen dennoch zwischen 2 FSBs zu vergleichen, kann ein Public Key des entsprechenden Eintrages erzeugt und mit anderen, ebenso erstellen Public Key verglichen werden.
Diese Public Keys müssen identisch für alle FSBs sein, die denselben Firm Code besitzen.
Zur Erzeugung eines benötigten Public Keys gehen Sie wie folgt vor:
1. Aufrufen Kern-API-Funktion CmAccess2() und Ausführen eines Entry-Access auf 99:<Ihr Firm Code>.
2. Erzeugen eines Public Keys mit diesem Zugriff (Handle) zusammen mit der Funktion CmGetPublicKey() und Verwenden des Secret Data Datenfeld-Typs 128.
Die obigen Schritte können z.B. auch mit CodeMeter API Guide durchgeführt werden.
Sie öffnen dieses Tool über das System-Menü "Start | Alle Programme | CodeMeter | Tools". - Um den Unit Counter (Nutzungseinheiten) eines Lizenzeintrags herunterzuzählen, wird zunächst ein Handle auf den Lizenzeintrag benötigt. Dieses kann mit der CmAccess2 Funktion erhalten werden.
Mit Hilfe des Handles kann dann eine Verschlüsselung mit CmCrypt2 durchgeführt werden. In der BaseCrypt-Struktur kann dann als Teil der EncryptionCodeOptions angegeben werden, um wieviele Nutzungseinheiten der Unit Counter reduziert werden soll.
z.B. cmBaseCrypt.EncryptionCodeOptions |= 1;
Hinweis: es können maximal 9999 Nutzungseinheiten auf einmal reduziert werden.
Zusätzlich kann über die EncryptionCodeOption noch konfiguriert werden, dass CmCrypt2:
- sicherstellt, dass ein Unit Counter vorhanden und dass dieser einen Wert > 0 hat
- kontrolliert, ob ein Unit Counter vorhanden ist und wenn dieser vorhanden ist, dass dieser einen Wert > 0 hat
- ignoriert, ob überhaupt ein Unit Counter vorhanden ist z.B. cmBaseCrypt.EncryptionCodeOptions |= (uint) CmBaseCrypt.EncCodeOption.UnitCounterCheck;
Beispielcode für die allgemeine Verwendung von CmCrypt2 finden Sie im CmCalculator-Beispiel unter:
C:\Users\Public\Documents\WIBU-SYSTEMS\SoftwareProtectionSamples.zip\C++\Special\CmCalculator\
CCMCalculatorDlg::DoRuntimeCheck
Zusätzliche Informationen zu den API-Funktionen finden Sie auch in der CodeMeter Kern API-Hilfe unter:
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\CodeMeter\Documentation |Core API Help - Um den True Random Number Generator (RNG) im CmDongle zu verwenden, können Sie die API-Funktion CmCalculateSignature() verwenden.
Diese benutzt im Hintergrund den RNG des CmDongles, um eine Signatur zu erstellen. Sie können die resultierende Signatur dann als Seed eines beliebigen softwareseitigen Zufallsgenerators verwenden.
Der CmCaluculateSignature()-Aufruf benötigt ein Handle auf einen CmDongle bzw. einem Firm Item/Lizenzeintrag auf einem CmDongle. Desweiteren wird eine CmAuthenticate-Struktur benötigt, die die Konfiguration enthält, die zur Erstellung der Signatur verwendet werden soll. Hier reichen SerialKey und Direct für das Ctrl-Feld aus.
Mehr Informationen finden Sie in der CodeMeter Core API-Hilfe (http://localhost:22352/%24api_help/CmAPIHelp/index.html?start.htm).