Crystal reaches the dongle through the SDK’s flat C API with function pointers resolved by name from the native library, which is loaded at run time, so nothing is linked and nothing sits in the path of the check that a customer could substitute for something more agreeable. No dependencies. The keynub_licdongle shard, Crystal 1.10 or later, on Windows, Linux and macOS; shards install brings the native libraries along.
# shard.yml
dependencies:
keynub_licdongle:
github: AB-KeyNub/KeyNub-SDK
version: 1.1.1-crystalCode language: Crystal (crystal)Reading a License
require "keynub_licdongle"
license = KeyNub::LicDongle.open do |d| # first dongle, or open("serial")
d.verify_genuine # raises unless genuine
d.session { d.read_record("license") } # closed on every exit path
endCode language: Crystal (crystal)What You Are Protecting
Crystal software that is sold ships as a native binary: a command-line tool, a service on a customer’s server, a data-processing engine. A check that returns a Bool is one conditional branch in that binary, and patching one of those is a beginner exercise.
So the strong pattern is the one to reach for: the data the program needs only exists when the dongle is present.
# Weak: one patched branch.
exit 1 unless d.genuine?
# Strong: the parameters only exist with the dongle present.
parameters = d.session do
decode_parameters(d.app_decrypt(sealed_blob_shipped_with_your_program))
endCode language: Crystal (crystal)Every failed call raises KeyNub::LicDongle::Error with the status (Status::NoDevice, Status::NotGenuine, Status::AuthRequired, …), the operation and the library’s detail; genuine? fails closed. The block forms of open and session release the dongle and the session on every exit path. The shard calls the SDK’s flat companion API, the one designed for foreign function interfaces: integer handles and buffers, no hand-written structure layouts.
Shipping the Native Library with a Crystal Application
The keynub_licdongle shard resolves the SDK’s flat API by name from the library it opens at run time (dlopen, LoadLibrary), so nothing is linked and there are no dependencies. shards install checks out the SDK repository with its natives/ folder, and the shard finds the library there during development. A shipped executable takes keynub_licdongle_flat for its platform beside it, where the shard looks first, or names it with KeyNub::LicDongle.library_path= or KEYNUB_LICDONGLE_FLAT_LIBRARY.
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 Crystal Developers Ask
Which Crystal Versions Does the Shard Support?
Crystal 1.10 and later, on Windows, Linux and macOS.
Does a Crystal 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 Crystal 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.
Does It Run on ARM: Windows on ARM, Apple Silicon, aarch64 Linux?
Yes. The SDK ships native libraries for Windows x64, x86 and ARM64, Linux x86_64 and aarch64, and universal macOS binaries for Intel and Apple silicon.
Can a License Written from Crystal 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: crystal/verify_and_read.cr. Binding source: bindings/crystal. 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
