Software License Dongle for Groovy

Groovy reaches the dongle through the SDK’s Java binding, com.keynub:keynub-licdongle on Maven Central, which calls the native library through JNA. A script pulls it in with one @Grab, and Groovy’s withCloseable closes the context, the dongle and the session on every exit path. Groovy 4 or later on Java 17 or later, on Windows, Linux and macOS.

@Grab('com.keynub:keynub-licdongle:1.1.1')
import com.keynub.licdongle.LicenseDongleContextCode language: Groovy (groovy)

Reading a License

byte[] license = new LicenseDongleContext().withCloseable { ctx ->
    ctx.open().withCloseable { dongle ->                // first dongle, or open(serial)
        dongle.verifyGenuine()                          // throws unless genuine
        dongle.openSession().withCloseable { session -> // closed on every exit path
            session.readRecord('license')
        }
    }
}Code language: Groovy (groovy)

What You Are Protecting

Groovy software that is sold runs on the JVM: an automation tool, a scripting layer in a desktop product, a service on a customer’s server. A script ships as source and compiled classes decompile readily, so a check that returns a boolean is one if to remove.

So the strong pattern is the one to reach for: the data the program needs only exists when the dongle is present.

// Weak: one removed branch.
try { dongle.verifyGenuine() } catch (LicenseDongleException e) { System.exit(1) }

// Strong: the parameters only exist with the dongle present.
def parameters = dongle.openSession().withCloseable { session ->
    decodeParameters(session.appDecrypt(sealedBlobShippedWithYourProgram))
}Code language: Groovy (groovy)

Every failure throws a LicenseDongleException whose status is a LicdStatus (NO_DEVICE, NOT_GENUINE, AUTH_REQUIRED, …) and whose detail is the library’s text, with subclasses such as NotGenuineException and RecordNotFoundException for the cases to catch separately. The context, the dongle and the session are AutoCloseable, so withCloseable closes each of them on every exit path; record data, keys and sealed data are byte[].

Shipping the Native Library with a Groovy Application

Groovy uses the Java binding com.keynub:keynub-licdongle, which carries no native library: a script or an application ships keynub_licdongle for its platform with it. The Java binding loads the library that the system property keynub.licdongle.library names, or one that JNA finds on jna.library.path or the system search path; the samples set the property to the library in a clone’s natives/<platform>/, or to the one KEYNUB_LICDONGLE_LIBRARY names.

The prebuilt libraries for every platform are in the SDK repository’s natives/<platform>/ folder, with a SHA-256 manifest: Windows x64, x86 and ARM64, Linux x86_64 and aarch64, and universal macOS binaries for Intel and Apple silicon. On Linux, install the udev rule from NATIVES.md once, so that ordinary users may open the device.

Questions Groovy Developers Ask

Which Groovy Versions Do the Samples Support?

Groovy 4 and later on Java 17 and later, on Windows, Linux and macOS, with the Java binding from Maven Central.

Which Binding Does a Groovy Program Use?

The Java binding, called directly: @Grab('com.keynub:keynub-licdongle:1.1.1') in a script, or the same coordinates in a Gradle or Maven build. The classes, the exceptions and the AutoCloseable resources are the Java binding’s.

Does a Groovy Application Need Administrator Rights to Talk to the Dongle?

No, and no driver either: the dongle is a USB HID device that the operating systems handle with their built-in class drivers. On Linux, install the shipped udev rule once so that ordinary users may open it; without the rule the SDK reports access denied and names the cause in its error detail.

Does a Groovy License Check Need an Internet Connection?

No. Verification is a local exchange between your program and the dongle over USB: the SDK checks the dongle’s certificate chain to KeyNub’s root and runs a live challenge-response. There is no activation server and no account, so the check works on air-gapped machines.

Who Can Read the License Records on a Dongle?

Anyone holding the dongle: a program opens a session and reads records, and can decrypt data sealed for that dongle. Writing records, erasing them and incrementing counters need your write key. What the dongle guarantees is that none of it is available without the dongle present.

Can a License Written from Groovy Be Read by a Program in Another Language?

Yes. Every binding drives the same core library and the same dongle, and records and sealed data are language-neutral bytes. Your issuing tool can be written in one language and your product in another.

Code

Runnable sample: groovy/VerifyAndRead.groovy. Binding source: bindings/java. Both are Apache-2.0, in the public SDK repository; the prebuilt native libraries are in the repository’s natives/ folder, one per platform.

All supported languages · All industries · Buy a KeyNub · Ask us something