Major Upgrades
Dieses Kapitel enthält wichtige Informationen zum Update zwischen Major Versionen der signoPAD-API Java. Es beschreibt die Änderungen, durch die ein Projekt nach dem Update der API nicht mehr kompilierbar ist.
Version 8.x auf 9.x
-
Veraltete (
@Deprecated) Methoden und Klassen entfernt. Entfernen Sie dessen Verwendung vor dem Upgrade der API. -
Minimale Java Version erhöht von JavaSE 6 auf JavaSE 7.
-
Package
de.signotec.STPadumbenannt inde.signotec.stpad -
Klasse
de.signotec.stpad.api.exceptions.Errorentfernt. Wird nicht mehr benötigt. -
Klasse
de.signotec.stpad.api.PenDisplayLibraryverschoben nachde.signotec.stpad.enums.PenDisplayLibrary. -
Top-Level Exception
de.signotec.stpad.api.exceptions.SigPadApiExceptiondurch neueSigPadExceptionersetzt. -
Methoden werfen jetzt auch Java Standard-Exceptions inkl. Unchecked Exceptions.
-
java.lang.IllegalArgumentExceptionbei ungültigen Parametern -
java.lang.IllegalStateExceptionwenn eine Funktion im aktuellen Status nicht ausgeführt werden kann. Z.B. wenn die Unterschriften-erfassung gestartet wird, ohne vorher den Unterschriftenbereich festzulegen. -
java.lang.UnsupportedOperationExceptionwenn die Funktion von dem Signaturgerät oder der Fassade nicht unterstützt wird. -
java.io.IOExceptionbei I/O Fehlern. -
java.security.SignatureExceptionbei Verarbeitung von biometrischen Daten und Fehlern in Kryptographie Funktionen.
-
-
Klassen
de.signotec.stpad.api.ForegroundBuffer,BackgroundBufferundPermanentStoreentfernt. Die API verwendet nur noch dessen gemeinsame Superklassede.signotec.stpad.api.ImageMemory. Der Speichertyp kann mit folgenden Methoden ermittelt werden:-
ImageMemory.isPermanentStore() -
ImageMemory.isForegroundBuffer() -
ImageMemory.isBackgroundBuffer() -
ImageMemory.isOverlayBuffer()
-
-
Klassen
de.signotec.stpad.control.SignatureJPanel, SignatureCanvasundSignatureWidgetreagieren nicht mehr auf dasSigPadListener.errorOccurred()Event. Der Fehler wird nicht mehr geloggt (Throwable.printStackTrack()) und dem Benutzer wird kein Fehlerdialog mehr angezeigt. -
Methode
de.signotec.stpad.api.SigPadApi.getSignatureData_Byte()umbenannt ingetSignatureDataBytes(). -
Methode
SignatureGraphics.setSampleRate(int)entfernt. Wird nicht mehr benötigt. -
Konstante
de.signotec.stpad.enums.RSAScheme.NoOIDumbenannt inNO_OID. -
Abhängigkeit zu
commons-codec-1.4Bibliothek entfernt. -
BouncyCastle auf Version 1.64 aktualisiert. Wenn es mit Java 7 zu JCE-Validierungsfehlern beim Laden der Bibliothek kommt, sollte ein alternatives Jar verwendet werden.
“Further Note (users of Oracle JVM 1.7 or earlier, users of "pre-Java 9" toolkits): As of 1.63 we have started including signed jars for "jdk15to18", if you run into issues with either signature validation in the JCE or the presence of the multi-release versions directory in the regular "jdk15on" jar files try the "jdk15to18" jars instead“
Details siehe https://www.bouncycastle.org/download/bouncy-castle-java/
Lizenzschlüssel
Die signoPAD-API Java wird im unregistrierten Zustand ausgeliefert. In diesem Zustand ist der Funktionsumfang während der Erfassung und Darstellung der Unterschrift auf einem Pen Display durch ein Wasserzeichen eingeschränkt. Bei Verwendung eines signotec Signature LCD Pad kann die API auch ohne Lizenzschlüssel uneingeschränkt verwendet werden.
Es existieren zwei unterschiedliche Arten von Lizenzschlüsseln:
-
Hardwaregebundene Einzelplatzlizenzen
-
Hardwareunabhängige Unternehmenslizenzen
Bei Lizenzen von Typ 1 wird bei der Installation ein Autorisationsschlüssel (Software-Code) generiert. Dieser ist an bestimmte Komponenten der Hardware gebunden und ist immer nur für einen Rechner gültig (Einzelplatz).
Mittels des mitgelieferten Programms license-tool/license-tool.exe kann nach Erwerb einer Einzelplatzlizenz ein Lizenzschlüssel beantragt und eingetragen werden.
Ist ein gültiger Lizenzschlüssel vorhanden, so wird dieser in der Registry des Computers hinterlegt und alle Komponenten der signoPAD-API Java sind damit vom Demostempel befreit.
Bei Lizenzen von Typ 2 handelt es sich um hardwareunabhängige Unternehmenslizenzen, die nicht an einen Rechner/Arbeitsplatz gebunden sind und bei der der Schlüssel nicht in der Registry hinterlegt wird. Stattdessen muss der Lizenzschlüssel vor Verwendung der API durch den Aufruf der Methode SigPadApi.setSerialKey() gesetzt werden.
Kommandozeilen-Tool stlic
Ergänzend zur Desktop-Anwendung license-tool/license-tool.exe enthält das Auslieferungspaket das Kommandozeilen-Tool stlic. Damit können Lizenzschlüssel ohne grafische Oberfläche aktiviert, entfernt, geprüft und angezeigt werden, z. B. auf headless Systemen wie Servern und Containern oder in automatisierten Rollouts mit Ansible, Docker oder Shell-Skripten. Das Tool ist primär für Linux gedacht und steht zusätzlich unter Windows zur Verfügung.
Desktop-Anwendung und stlic verwenden denselben Lizenzspeicher. Eine mit einem der beiden Programme aktivierte Lizenz ist auch im anderen sichtbar.
|
Plattform |
Aufruf |
|---|---|
|
Linux |
|
|
Windows |
|
Voraussetzung ist eine 64-Bit Java Runtime ab Version 8. Unter Linux muss java im PATH liegen, unter Windows wird die Runtime aus JAVA_HOME oder dem PATH verwendet.
Alle Ausgaben, Parameter und Hilfetexte von stlic sind unabhängig von der Systemsprache ausschließlich englisch. Eine ausführliche Beschreibung mit allen Ausgaben enthält die Datei license-tool/README.md. Die Hilfe ist auch direkt über stlic --help bzw. stlic <command> --help abrufbar.
stlic [--quiet] [-v | --verbose] [--non-interactive] <command> [<arguments>]
stlic -h | --help
stlic -V | --version
Kommandos
Jeder Aufruf führt genau ein Kommando für genau ein Produkt aus. Als <product> wird die Produkt-ID angegeben, Groß- und Kleinschreibung spielen dabei keine Rolle. Folgende Produkte werden unterstützt:
|
Produkt-ID |
Produkt |
|---|---|
|
|
signoAPI Java |
|
|
signoPAD-API Java |
Bei einer unbekannten Produkt-ID bricht das Kommando mit Exit-Code 4 ab und listet die gültigen IDs auf.
|
Kommando |
Beschreibung |
|---|---|
|
|
Prüft den Lizenzschlüssel und speichert ihn für das Produkt. Ist das Produkt bereits mit einem gültigen Schlüssel lizenziert, wird die Aktivierung abgelehnt, außer es wird |
|
|
Entfernt den Lizenzschlüssel des Produkts. Ohne |
|
|
Zeigt ohne Argument alle aktivierten Lizenzen mit Schlüssel an. Mit Produkt-ID wird nur dieses Produkt angezeigt, Exit-Code 1 bedeutet dann, dass das Produkt nicht lizenziert ist. |
|
|
Prüft, ob der Lizenzschlüssel für das Produkt gültig ist. Der Schlüssel wird dabei nie gespeichert, auch nicht bei Gültigkeit. |
|
|
Gibt den hardwaregebundenen Software-Code des Rechners aus, der für die Beantragung einer Einzelplatzlizenz benötigt wird. Der Code ist für alle Produkte gleich. |
Eine Lizenzanforderung per E-Mail wie in der Desktop-Anwendung ist mit stlic nicht möglich. Senden Sie stattdessen den mit stlic code ermittelten Software-Code an die signotec GmbH.
Optionen
|
Option |
Wirkung |
|---|---|
|
|
Bei |
|
|
Fragt nie nach einer Bestätigung, auch wenn ein Terminal angeschlossen ist. Ein Kommando, das eine Bestätigung benötigt, schlägt stattdessen fehl. Ohne angeschlossenes Terminal verhält sich |
|
|
Unterdrückt alle nicht notwendigen Ausgaben. |
|
|
Gibt bei einem Fehler zusätzlich den Java Stack Trace aus. |
Die Optionen können vor oder nach dem Kommando angegeben werden. stlic liest weder eine Konfigurationsdatei noch Umgebungsvariablen, alle Einstellungen werden als Argumente übergeben. Fehlermeldungen werden immer auf stderr, reguläre Ausgaben auf stdout ausgegeben.
Exit-Codes
|
Code |
Bedeutung |
|---|---|
|
0 |
Erfolg |
|
1 |
Ungültiger Lizenzschlüssel ( |
|
2 |
Der Lizenzspeicher konnte nicht gelesen oder geschrieben werden (Storage-Fehler) |
|
3 |
Fehlende Berechtigung zum Schreiben des Lizenzspeichers ( |
|
4 |
Ungültige Aufrufparameter, z. B. unbekanntes Produkt, fehlendes Argument, bereits lizenziertes Produkt ohne |
|
5 |
Die native Lizenzbibliothek ist nicht verwendbar |
|
6 |
Unerwarteter Fehler |
Berechtigungen
Die Lizenzschlüssel werden rechnerweit in den Java System Preferences gespeichert, unter Linux unterhalb von /etc/.java/.systemPrefs und unter Windows in der Registry unterhalb von HKEY_LOCAL_MACHINE. Für activate und remove sind daher Schreibrechte erforderlich: unter Linux root-Rechte (z. B. mit sudo), unter Windows eine als Administrator gestartete Konsole. Fehlen die Rechte, bricht das Kommando mit einer Fehlermeldung und Exit-Code 3 ab.
status, validate und code lesen nur und können von jedem Benutzer ausgeführt werden.
Beispiele
# Software-Code für die Beantragung einer Einzelplatzlizenz ermitteln
stlic code
# Lizenz aktivieren
sudo stlic activate signopad-api-java 0123456789ABCDEF
# Lizenzstatus im Skript auswerten
if stlic status signopad-api-java --quiet > /dev/null; then
echo "licensed"
fi
# Lizenz ohne Rückfrage entfernen
sudo stlic remove signopad-api-java --force
Datenformate
Unterschriften können als BMP, WBMP, JPEG, PNG, GIF, JPEG 2000, PNM, RAW und TIFF ausgegeben werden. In der Regel sollten Sie PNG verwenden, weil es die besten Ergebnisse bei kleinster Dateigröße bietet. JPEG ist ein Bildformat mit einer verlustbehafteten Komprimierung und wird nicht empfohlen.
SignData Strukturen
Die signoPAD-API Komponenten können eine erfasste Unterschrift als Datenstruktur im SignData Format zurückliefern. Es ist ein verschlüsseltes, komprimiertes, biometrisches Format, das in einer Datenbank und oder als Tag in einem TIFF-Dokument oder einem PDF-Dokument hinterlegt werden kann.
Für die (ISO-konforme) Signatur von PDF und TIFF-Dokumenten steht ein separates API (signoAPI) zur Verfügung. Dieses beinhaltet weitreichende Funktionen zum PDF-Management und vieles mehr. Bei Interesse fragen Sie bitte Ihren Kontakt bei signotec danach.
SignData-Strukturen können durch Implementierung des Interface SigPadListener aus dem Package de.signotec.stpad.api.events in Echtzeit visualisiert werden. Die Klassen SignatureCanvas (AWT), SignatureJPanel (Swing) und SignatureWidget (SWT) implementieren dieses Interface bereits und werden daher zur Visualisierung der Unterschriftenerfassung empfohlen.
Sicherheitskritische Daten
Passwörter und private Schlüssel gehören zu den sicherheitskritischen Daten und müssen mit besonderer Sorgfalt behandelt werden. Bei Verwendung dieser API sollten Sie neben den gängigen Sicherheitsstandards folgendes beachten, um das Sicherheitsniveau Ihrer Software möglichst hochzuhalten.
-
Für Passwörter nur überschreibbare Datenstrukturen verwenden.
Die signoPAD-API Java verwendet den Datentyp
char[]. Die Daten eines unveränderlichen Typs wieStringkönnen nicht gezielt überschrieben bzw. gelöscht werden und verbleiben u.U. sehr lange im Arbeitsspeicher. -
Passwörter unmittelbar nach Verwendung löschen.
Um das Zeitfenster für das Auslesen von Passwörtern aus dem Arbeitsspeicher so kurz wie möglich zu halten, sollten sie sofort nach Verwendung überschrieben werden. Die signoPAD-API Java bietet dafür die Methode
KeyLoader.clearPassword(char[]). -
Private Schlüssel unmittelbar nach Verwendung löschen.
Seit Java 8 sollten Schlüssel, die das
DestroyableInterface implementieren, mit der Methodedestroy()im Speicher überschrieben/unkenntlich gemacht werden sobald sie nicht mehr benötigt werden.