German English
German English

signoPAD-API Java - General Information

Major upgrades

This section contains key information you will need when updating from one major version of signoPAD-API Java to another. It also describes the changes that make it no longer possible to compile a project after the API is updated.

Version 8.x to 9.x

  • Outdated (@Deprecated) methods and classes deleted. Remove from use before upgrading the API.

  • Minimum Java version increased from JavaSE 6 to JavaSE 7.

  • The de.signotec.STPad package has been renamed de.signotec.stpad

  • The de.signotec.stpad.api.exceptions.Error class has been removed; it is no longer required.

  • The de.signotec.stpad.api.PenDisplayLibrary class has been moved to de.signotec.stpad.enums.PenDisplayLibrary.

  • The de.signotec.stpad.api.exceptions.SigPadApiException top-level exception has been replaced by SigPadException (new).

  • Methods now also throw standard exceptions (including unchecked exceptions).

    • java.lang.IllegalArgumentException in the event of invalid parameters.

    • java.lang.IllegalStateException if a function cannot be carried out in the current status, for example, if signature capture is started without first defining the signature area.

    • java.lang.UnsupportedOperationException if the function is not supported by the signature device or by the facade.

    • java.io.IOException in the event of I/O errors.

    • java.security.SignatureException when processing biometric data and errors to cryptography functions.

  • The de.signotec.stpad.api.ForegroundBuffer, BackgroundBuffer and PermanentStore classes have been removed. The API now only uses its shared de.signotec.stpad.api.ImageMemory superclass. It is possible to use the following methods to identify the memory type:

    • ImageMemory.isPermanentStore()

    • ImageMemory.isForegroundBuffer()

    • ImageMemory.isBackgroundBuffer()

    • ImageMemory.isOverlayBuffer()

  • The de.signotec.stpad.control.SignatureJPanel, SignatureCanvas and SignatureWidget classes no longer respond to the SigPadListener.errorOccurred() event. The error is no longer logged (Throwable.printStackTrack()), and the user is no longer shown an error dialog.

  • The de.signotec.stpad.api.SigPadApi.getSignatureData_Byte() method has been renamed getSignatureDataBytes().

  • The SignatureGraphics.setSampleRate(int) method has been removed; it is no longer required.

  • The de.signotec.stpad.enums.RSAScheme.NoOID constant has been renamed NO_OID.

  • Dependency to the commons-codec-1.4 library has been removed.

  • BouncyCastle updated to version 1.64. If JCE validation errors occur with Java 7 when loading the library, an alternative JAR file should be used.

    “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.”

    For more information, see https://www.bouncycastle.org/download/bouncy-castle-java/.

Licence keys

signoPAD-API Java is unregistered when it is delivered. In this state, the range of functions is restricted by a watermark when capturing and displaying the signature on a pen display. If you are using a signotec signature LCD pad, unrestricted use of the API is possible even without licence keys.

There are two different types of licence keys:

  1. Hardware-dependent single-user licences

  2. Hardware-independent company licences

For type 1 licences, an authorisation key (software code) is generated during installation. This key is bound to specific hardware components and is only ever valid for one computer (single user).

After a single-user licence has been purchased, a licence key can be requested and entered with the help of the supplied license-tool/license-tool.exe program.

As soon as a valid licence key is available, this is stored in the computer’s registry and the demo stamp is removed from all SignoPAD API for Java components.

Type 2 licences are hardware-independent company licences that are not bound to one particular computer/workstation and whose keys are not stored in the registry. Instead, the licence key must be set before using the API by calling the SigPadApi.setSerialKey() method.

Command line tool stlic

In addition to the desktop application license-tool/license-tool.exe, the delivery package contains the command line tool stlic. It can be used to activate, remove, check and display licence keys without a graphical user interface, e.g. on headless systems such as servers and containers or in automated rollouts with Ansible, Docker or shell scripts. The tool is primarily intended for Linux and is also available for Windows.

The desktop application and stlic use the same licence storage. A licence activated with one of the two programs is also visible in the other.

Platform

Call

Linux

license-tool/stlic (shell script)

Windows

license-tool/stlic.exe (console application)

A 64-bit Java runtime, version 8 or later, is required. On Linux, java must be on the PATH. On Windows, the runtime from JAVA_HOME or from the PATH is used.

All output, parameters and help texts of stlic are in English only, regardless of the system language. A detailed description including all output is provided in the file license-tool/README.md. The help can also be shown directly with stlic --help or stlic <command> --help.

stlic [--quiet] [-v | --verbose] [--non-interactive] <command> [<arguments>]
stlic -h | --help
stlic -V | --version

Commands

Each call runs exactly one command for exactly one product. The <product> argument takes the product ID; upper and lower case do not matter. The following products are supported:

Product ID

Product

signoapi-java

signoAPI Java

signopad-api-java

signoPAD-API Java

If the product ID is unknown, the command fails with exit code 4 and lists the valid IDs.

Command

Description

activate <product> <license-key>

Checks the licence key and stores it for the product. If the product is already licensed with a valid key, the activation is refused unless --force is given.

remove <product>

Removes the licence key of the product. Without --force, a confirmation is requested. The command also succeeds if no key is stored.

status [<product>]

Without an argument, shows all activated licences including their keys. With a product ID, only this product is shown; exit code 1 then means that the product is not licensed.

validate <product> <license-key>

Checks whether the licence key is valid for the product. The key is never stored, not even if it is valid.

code

Shows the hardware-dependent software code of the computer, which is required to request a single-user licence. The code is the same for all products.

Requesting a licence by e-mail as in the desktop application is not possible with stlic. Instead, send the software code determined with stlic code to signotec GmbH.

Options

Option

Effect

--force

With activate: overwrites an existing valid activation. With remove: removes the licence without confirmation.

--non-interactive

Never asks for confirmation, even if a terminal is attached. A command that requires a confirmation fails instead. Without an attached terminal, stlic automatically behaves this way.

--quiet

Suppresses all output that is not essential. status then prints one machine-readable line per product in the format <key><TAB><id>. Error messages are still printed.

-v, --verbose

Additionally prints the Java stack trace if an error occurs.

The options can be given before or after the command. stlic reads neither a configuration file nor environment variables; all settings are passed as arguments. Error messages are always written to stderr, regular output to stdout.

Exit codes

Code

Meaning

0

Success

1

Invalid licence key (activate, validate) or the given product is not licensed (status <product>)

2

The licence storage could not be read or written (storage error)

3

No permission to write the licence storage (activate, remove)

4

Invalid arguments, e.g. unknown product, missing argument, product already licensed without --force or missing confirmation

5

The native licence library is not usable

6

Unexpected error

Permissions

The licence keys are stored machine-wide in the Java system preferences: on Linux below /etc/.java/.systemPrefs and on Windows in the registry below HKEY_LOCAL_MACHINE. Write permission is therefore required for activate and remove: root privileges on Linux (e.g. with sudo), a console started as administrator on Windows. Without this permission, the command fails with an error message and exit code 3.

status, validate and code only read and can be run by any user.

Examples

Bash
# Show the software code required to request a single-user licence
stlic code

# Activate a licence
sudo stlic activate signopad-api-java 0123456789ABCDEF

# Evaluate the licence status in a script
if stlic status signopad-api-java --quiet > /dev/null; then
    echo "licensed"
fi

# Remove a licence without confirmation
sudo stlic remove signopad-api-java --force

Data formats

Signatures can be output in BMP, WBMP, JPEG, PNG, GIF, JPEG 2000, PNM, RAW and TIFF format. Generally speaking, you should use PNG as it offers the best results with the smallest file size. JPEG is an image format with lossy compression and is not recommended.

SignData structures

The signoPAD API components can return a captured signature as a SignData data structure. It is an encrypted, compressed, biometric format that can be stored in a database and/or as a tag in a TIFF document or a PDF document.

A separate API (signoAPI) is available for the (ISO-compliant) signature of PDF and TIFF documents. This API includes a wide range of functions for PDF management along with much more. Please contact your signotec contact if you are interested.

SignData structures can be visualised in real time by implementing the SigPadListener interface from the de.signotec.stpad.api.events package. The SignatureCanvas (AWT), SignatureJPanel (Swing) and SignatureWidget (SWT) classes already implement this interface and are therefore recommended for visualising signature capture.

Security-critical data

Passwords and private keys are considered security-critical data and must be handled especially carefully. When using this API, you should observe the following precautions in addition to common security standards in order to keep your software’s security level as high as possible.

  • For passwords, only use data structures that can be overwritten.

    signoPAD-API Java uses the char[] data type. Data of an unchangeable type such as string cannot be deliberately overwritten or deleted and may remain in RAM for a very long time under certain circumstances.

  • Passwords should be deleted immediately after use.

    To minimise the time frame in which passwords can be read from RAM, they should be overwritten immediately after use. The signoPAD-API Java offers the method KeyLoader.clearPassword(char[]) for this purpose.

  • Delete private keys immediately after use.

    For Java 8 and later versions, keys that implement the Destroyable interface should be overwritten/rendered unrecognisable in memory via the destroy() method once they are no longer needed.