German English
German English

signoPAD-API Java - Allgemeine Hinweise

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.STPad umbenannt in de.signotec.stpad

  • Klasse de.signotec.stpad.api.exceptions.Error entfernt. Wird nicht mehr benötigt.

  • Klasse de.signotec.stpad.api.PenDisplayLibrary verschoben nach de.signotec.stpad.enums.PenDisplayLibrary.

  • Top-Level Exception de.signotec.stpad.api.exceptions.SigPadApiException durch neue SigPadException ersetzt.

  • Methoden werfen jetzt auch Java Standard-Exceptions inkl. Unchecked Exceptions.

    • java.lang.IllegalArgumentException bei ungültigen Parametern

    • java.lang.IllegalStateException wenn 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.UnsupportedOperationException wenn die Funktion von dem Signaturgerät oder der Fassade nicht unterstützt wird.

    • java.io.IOException bei I/O Fehlern.

    • java.security.SignatureException bei Verarbeitung von biometrischen Daten und Fehlern in Kryptographie Funktionen.

  • Klassen de.signotec.stpad.api.ForegroundBuffer, BackgroundBuffer und PermanentStore entfernt. Die API verwendet nur noch dessen gemeinsame Superklasse de.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, SignatureCanvas und SignatureWidget reagieren nicht mehr auf das SigPadListener.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 in getSignatureDataBytes().

  • Methode SignatureGraphics.setSampleRate(int) entfernt. Wird nicht mehr benötigt.

  • Konstante de.signotec.stpad.enums.RSAScheme.NoOID umbenannt in NO_OID.

  • Abhängigkeit zu commons-codec-1.4 Bibliothek 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:

  1. Hardwaregebundene Einzelplatzlizenzen

  2. 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

license-tool/stlic (Shell-Skript)

Windows

license-tool/stlic.exe (Konsolenanwendung)

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

signoAPI Java

signopad-api-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

activate <product> <license-key>

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 --force angegeben.

remove <product>

Entfernt den Lizenzschlüssel des Produkts. Ohne --force wird eine Bestätigung abgefragt. Das Kommando ist auch erfolgreich, wenn kein Schlüssel gespeichert ist.

status [<product>]

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.

validate <product> <license-key>

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.

code

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

--force

Bei activate: überschreibt eine bestehende gültige Aktivierung. Bei remove: entfernt die Lizenz ohne Rückfrage.

--non-interactive

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 stlic automatisch so.

--quiet

Unterdrückt alle nicht notwendigen Ausgaben. status gibt dann maschinenfreundlich eine Zeile pro Produkt im Format <key><TAB><id> aus. Fehlermeldungen werden weiterhin ausgegeben.

-v, --verbose

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 (activate, validate) bzw. das angegebene Produkt ist nicht lizenziert (status <product>)

2

Der Lizenzspeicher konnte nicht gelesen oder geschrieben werden (Storage-Fehler)

3

Fehlende Berechtigung zum Schreiben des Lizenzspeichers (activate, remove)

4

Ungültige Aufrufparameter, z. B. unbekanntes Produkt, fehlendes Argument, bereits lizenziertes Produkt ohne --force oder fehlende Bestätigung

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

Bash
# 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 wie String kö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 Destroyable Interface implementieren, mit der Methode destroy() im Speicher überschrieben/unkenntlich gemacht werden sobald sie nicht mehr benötigt werden.