keynub_licdongle 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b4e6087fb299d00885c4fc56d124188a9fb87d500755a388ddf2062ebd0ad5a
+  data.tar.gz: 9f772865a5cf6a98083273832dc61c987a7a53faa1490b6a4e34cc03ee9d0276
+SHA512:
+  metadata.gz: cf8163cfabf981bad451ad8e14b3f36a5a96ebdfabf6ec6539005d9c0d9562e8af1e3c8232c58f105bd24c7c5927a71a91e2cc337eeb477529ba1505dffd6809
+  data.tar.gz: 62dd686dce927513a341d23689b02e501c4b0f423cfcff71923b06e40edaf7f11fd3c27c7a0f487bbfebac0def34cebfcbb3bf22943b96682a7d650be9c8af58

data/BINARY-LICENSE.txt

@@ -0,0 +1,91 @@
+================================================================================
+ KEYNUB LICENSE DONGLE SDK
+ Licence for the prebuilt native libraries
+================================================================================
+
+This distribution contains two kinds of thing, under two different licences.
+
+
+1. SOURCE - Apache License, Version 2.0
+--------------------------------------------------------------------------------
+
+The language bindings, the samples and the C ABI header are licensed under the
+Apache License, Version 2.0. The full text is in the accompanying LICENSE file,
+and the source is published at https://github.com/AB-KeyNub/KeyNub-SDK.
+
+
+2. PREBUILT NATIVE LIBRARIES - these terms
+--------------------------------------------------------------------------------
+
+The compiled libraries - keynub_licdongle, keynub_licdongle_flat and the KeyNub
+COM server, supplied as .dll and .lib, .so, .dylib and .a - are not published as
+source and are NOT licensed under Apache-2.0. They are licensed as follows.
+
+GRANT
+
+    Subject to these terms, KeyNub grants you a worldwide, royalty-free,
+    non-exclusive licence to:
+
+    (a) use and reproduce the libraries to develop, test and support your own
+        application; and
+
+    (b) distribute the libraries, in binary form, as an integral component of
+        that application, to your customers and end users.
+
+CONDITIONS
+
+    (1) You distribute the libraries unmodified.
+
+    (2) You distribute them only as a component of your own application - not as
+        a standalone product, library, SDK or download, and not in a form whose
+        principal purpose is to supply the libraries to others.
+
+    (3) You keep this file, LICENSE, NOTICE and THIRD-PARTY-NOTICES.txt with any
+        distribution that includes the libraries, and you do not remove or alter
+        any copyright, trademark or attribution notice they contain.
+
+    (4) You do not sublicense, rent, lease or sell the libraries on their own.
+
+RESERVED RIGHTS
+
+    No rights are granted in the "KeyNub" name, logo or other trademarks. All
+    rights not expressly granted above are reserved by KeyNub.
+
+YOUR STATUTORY RIGHTS
+
+    Nothing in these terms restricts any right you have under applicable law that
+    cannot be restricted by agreement. In the European Union, for example, that
+    includes the right to decompile for interoperability purposes under Article 6
+    of Directive 2009/24/EC.
+
+
+3. THIRD-PARTY COMPONENTS
+--------------------------------------------------------------------------------
+
+The libraries statically link Mbed TLS and hidapi. The licences KeyNub has elected
+for them, their copyright notices and the full licence texts are in
+THIRD-PARTY-NOTICES.txt. Those attribution obligations apply to you as well when
+you redistribute the libraries inside your application.
+
+
+4. NO WARRANTY
+--------------------------------------------------------------------------------
+
+THE LIBRARIES ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+
+5. LIMITATION OF LIABILITY
+--------------------------------------------------------------------------------
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, KEYNUB SHALL NOT BE LIABLE FOR
+ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF
+PROFITS, REVENUE OR DATA, ARISING OUT OF OR IN CONNECTION WITH THE LIBRARIES OR
+THEIR USE. Nothing in these terms excludes or limits liability that cannot be
+excluded or limited under applicable law.
+
+
+--------------------------------------------------------------------------------
+Questions about these terms, or about a use they do not cover - OEM redistribution,
+source escrow, an unusual platform: https://www.keynub.com/#contact

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/NOTICE

@@ -0,0 +1,14 @@
+KeyNub License Dongle SDK
+Copyright (c) 2026 KeyNub
+
+This product includes software developed as part of the KeyNub License Dongle
+SDK (https://github.com/AB-KeyNub/KeyNub-SDK). The bindings, samples and C ABI
+header published there are licensed under the Apache License, Version 2.0; see
+the LICENSE file for the full terms. The prebuilt native libraries are not
+published as source and are covered by the accompanying BINARY-LICENSE.txt.
+
+This product also includes third-party software. The native library
+(keynub_licdongle) statically links Mbed TLS and hidapi; the Java binding
+depends on JNA. Their copyright notices, the licenses elected for them, and the
+full text of those licenses are recorded in THIRD-PARTY-NOTICES.txt, which is
+distributed with this product.

data/README.md

@@ -0,0 +1,95 @@
+# KeyNub License Dongle — Ruby binding
+
+`keynub_licdongle` — the KeyNub dongle from Ruby. **No gems, no compiler**: the
+FFI layer is [Fiddle](https://docs.ruby-lang.org/en/master/Fiddle.html), which is
+part of Ruby's standard library. Ruby 3.0+, Windows / Linux / macOS.
+
+```ruby
+require 'keynub_licdongle'
+
+KeyNubLicDongle::Context.open do |ctx|
+  dongle = ctx.open              # first dongle, or ctx.open(serial)
+  dongle.verify_genuine!         # raises unless genuine
+
+  dongle.session do |session|
+    data = session.app_decrypt(blob)   # <- build your licence check on this
+  end
+end
+```
+
+> Read [`../../docs/integration-security.md`](https://github.com/AB-KeyNub/KeyNub-SDK/blob/master/docs/integration-security.md)
+> first. `exit unless licensed?` is one line to delete, and Ruby ships as source —
+> even a `.rbc` or an obfuscator only slows that down. What cannot be deleted is
+> data the program needs and only the dongle can decrypt.
+
+## Why no `ffi` gem
+
+The `ffi` gem is the usual choice and it is a fine library. Fiddle wins here for
+one reason that matters specifically to licensing: it is **already in the standard
+library**, so the check has no third-party dependency that a customer could
+replace with a stub of their own. Nothing to install, nothing to build, nothing in
+the load path but Ruby itself.
+
+The cost is that the C signatures live in
+[`lib/keynub_licdongle/native.rb`](https://github.com/AB-KeyNub/KeyNub-SDK/blob/master/bindings/ruby/lib/keynub_licdongle/native.rb) as data no
+compiler verifies — which is why every one of them is written out by hand. Struct
+layouts go through `Fiddle::Importer`, so the padding is computed rather than
+hand-maintained; a hand-written offset that is wrong reads a neighbouring field
+and produces a plausible wrong value rather than a crash.
+
+## Errors
+
+Failures raise `KeyNubLicDongle::Error` or a subclass, each carrying `status`
+(the numeric `licd_status`), `operation`, and `detail` (the SDK's diagnostic text).
+
+```ruby
+begin
+  dongle.verify_genuine!
+rescue KeyNubLicDongle::DeviceNotFoundError
+  warn 'please insert your KeyNub dongle'
+rescue KeyNubLicDongle::CertificateInvalidError => e
+  warn "this dongle was rejected: #{e.detail}"
+end
+```
+
+`dongle.genuine?` is the non-raising form for a gate and **fails closed**: a
+missing dongle, an I/O error and an invalid certificate all return `false`.
+
+Blocks close things for you — `Context.open`, `dongle.session` — and are the
+recommended form; `#close` is there when the lifetime is not lexical.
+
+## Progress callbacks
+
+`read_record` and `write_record` take a block called as `(done, total)`. Return
+`false` to cancel, which raises `OperationCancelledError`. An exception raised
+inside the block is held until the SDK has unwound its own transfer and then
+re-raised with its own identity — letting it escape through the C frames would
+skip that cleanup and strand the device mid-transfer.
+
+```ruby
+data = session.read_record('license') do |done, total|
+  print "\r#{done}/#{total}"
+  true
+end
+```
+
+## Shipping the native library
+
+The binding looks for the core library, in order:
+
+1. `KEYNUB_LICDONGLE_LIBRARY` — an absolute path to a specific library
+2. `vendor/` inside the gem
+3. beside `lib/keynub_licdongle/`
+4. the system search path
+
+## License
+
+Apache-2.0, like the rest of the SDK — [`../../LICENSE`](https://github.com/AB-KeyNub/KeyNub-SDK/blob/master/LICENSE),
+[`../../THIRD-PARTY-NOTICES.txt`](https://github.com/AB-KeyNub/KeyNub-SDK/blob/master/THIRD-PARTY-NOTICES.txt).
+
+## Links
+
+- [KeyNub License Dongle for Ruby](https://www.keynub.com/developers/ruby/): the product, and how to
+  order one
+- [Source, samples and issue tracker](https://github.com/AB-KeyNub/KeyNub-SDK) on GitHub
+- [Native library for your platform](https://github.com/AB-KeyNub/KeyNub-SDK/blob/master/NATIVES.md)

data/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,107 @@
+================================================================================
+ THIRD-PARTY NOTICES - KeyNub License Dongle SDK
+================================================================================
+
+The KeyNub License Dongle SDK's published source - the language bindings, the
+samples and the C ABI header, as published at
+https://github.com/AB-KeyNub/KeyNub-SDK - is licensed under the Apache License,
+Version 2.0 (see the accompanying LICENSE file).
+
+The prebuilt native libraries (keynub_licdongle, keynub_licdongle_flat and the
+KeyNub COM server) are not published as source and are NOT licensed under
+Apache-2.0. Their distribution terms are in the accompanying BINARY-LICENSE.txt.
+
+Either way, this distribution incorporates the third-party components listed
+below, and their attribution obligations travel with every copy of it.
+
+Several of these components are offered by their authors under a CHOICE of
+licenses. For each one, the license KeyNub has elected is stated explicitly, and
+the options that are not elected are named so there is no ambiguity about which
+terms apply to this distribution. Where Apache-2.0 is elected, the text in the
+accompanying LICENSE file is the applicable license text.
+
+Components marked "statically linked" are compiled into the native library
+(keynub_licdongle.dll / libkeynub_licdongle.so / libkeynub_licdongle.dylib).
+Their attribution obligations therefore travel with every binary distribution of
+the SDK - the NuGet package, the Python wheel, the Maven JAR, and the C/Delphi
+archives each carry a copy of this file alongside LICENSE and NOTICE.
+
+--------------------------------------------------------------------------------
+ 1. Mbed TLS 3.6.7  -  statically linked into the native library
+--------------------------------------------------------------------------------
+
+    Project:  https://github.com/Mbed-TLS/mbedtls  (tag mbedtls-3.6.7)
+    Offered:  dual license - Apache-2.0 OR GPL-2.0-or-later
+    ELECTED:  Apache-2.0
+              The GPL-2.0-or-later option is NOT elected and does not apply to
+              this distribution.
+
+    Copyright The Mbed TLS Contributors
+
+    Licensed under the Apache License, Version 2.0. The full text of that
+    license is in the accompanying LICENSE file.
+
+--------------------------------------------------------------------------------
+ 2. hidapi 0.15.0  -  statically linked into the native library
+--------------------------------------------------------------------------------
+
+    Project:  https://github.com/libusb/hidapi  (tag hidapi-0.15.0)
+    Offered:  a choice of three licenses - GPL-3.0, a BSD-style license, or the
+              more liberal original HIDAPI license
+    ELECTED:  the BSD-style license (hidapi's LICENSE-bsd.txt), reproduced in
+              full below.
+              The GPL-3.0 option is NOT elected and does not apply to this
+              distribution. Note that some operating-system distributions
+              package hidapi under GPL-3.0; that packaging is unrelated to this
+              distribution, which vendors hidapi from source under the terms
+              below.
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+Copyright (c) 2010, Alan Ott, Signal 11 Software
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Signal 11 Software nor the names of its
+      contributors may be used to endorse or promote products derived from
+      this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+--------------------------------------------------------------------------------
+ 3. Java Native Access (JNA) 5.14.0  -  Java binding only
+--------------------------------------------------------------------------------
+
+    Project:  https://github.com/java-native-access/jna
+    Offered:  dual license - LGPL-2.1-or-later OR Apache-2.0
+    ELECTED:  Apache-2.0
+              The LGPL-2.1-or-later option is NOT elected and does not apply to
+              this distribution.
+
+    Copyright (c) 2007-2023 Timothy Wall, Wayne Meissner, Matthias Bläsing and
+    the JNA contributors
+
+    JNA is a dependency of the Java binding only. It is resolved from Maven
+    Central at build time and is NOT redistributed inside the KeyNub JAR; it is
+    recorded here so that consumers assembling a distribution have the election
+    in writing. Licensed under the Apache License, Version 2.0 - full text in
+    the accompanying LICENSE file.
+
+================================================================================

data/lib/keynub_licdongle/errors.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module KeyNubLicDongle
+  # Native status codes (mirrors licd_status). OK is 0; errors are negative.
+  module Status
+    OK = 0
+    INVALID_ARGUMENT = -1
+    NO_DEVICE = -2
+    ACCESS_DENIED = -3
+    IO = -4
+    TIMEOUT = -5
+    PROTOCOL = -6
+    NOT_GENUINE = -7
+    CERTIFICATE_INVALID = -8
+    SESSION_EXPIRED = -9
+    TAG_MISMATCH = -10
+    RANGE = -11
+    STORAGE_FULL = -12
+    BUSY = -13
+    NOT_FOUND = -14
+    AUTH_REQUIRED = -15
+    FIRMWARE_INCOMPATIBLE = -16
+    SDK_TOO_OLD = -17
+    CANCELLED = -18
+    NOT_IMPLEMENTED = -19
+    INTERNAL = -20
+  end
+
+  # Raised when a native operation fails. +status+ carries the specific code and
+  # +detail+ the SDK's diagnostic text — log it, do not parse it.
+  class Error < StandardError
+    attr_reader :status, :operation, :detail
+
+    def initialize(status, message, operation: nil, detail: nil)
+      super(message)
+      @status = status
+      @operation = operation
+      @detail = detail.to_s
+    end
+  end
+
+  # The dongle failed its authenticity (challenge-response) check.
+  class NotGenuineError < Error; end
+  # The device certificate, or its chain to the trusted root, was invalid.
+  class CertificateInvalidError < Error; end
+  # The operation needs the write role (see Session#authorize_write).
+  class WriteAuthorizationRequiredError < Error; end
+  # No session for an operation that requires one, or it expired.
+  class SessionExpiredError < Error; end
+  # No matching dongle was found or present.
+  class DeviceNotFoundError < Error; end
+  # The named record does not exist on the dongle.
+  class RecordNotFoundError < Error; end
+  # A transfer was cancelled from its progress callback.
+  class OperationCancelledError < Error; end
+
+  SUBCLASS = {
+    Status::NOT_GENUINE => NotGenuineError,
+    Status::CERTIFICATE_INVALID => CertificateInvalidError,
+    Status::AUTH_REQUIRED => WriteAuthorizationRequiredError,
+    Status::SESSION_EXPIRED => SessionExpiredError,
+    Status::NO_DEVICE => DeviceNotFoundError,
+    Status::NOT_FOUND => RecordNotFoundError,
+    Status::CANCELLED => OperationCancelledError
+  }.freeze
+  private_constant :SUBCLASS
+
+  module_function
+
+  # Builds the error type that goes with +status+ without raising it.
+  def build_error(status, operation, detail = '')
+    text = Native.read_c_string(Native.call(:licd_strerror, status))
+    message = "#{operation}: #{text}"
+    message += " (#{detail})" unless detail.to_s.empty?
+    (SUBCLASS[status] || Error).new(status, message, operation: operation, detail: detail)
+  end
+
+  # Raises the mapped error unless +status+ is OK.
+  def check(status, operation, ctx_handle = nil)
+    return if status == Status::OK
+
+    detail = ctx_handle ? Native.read_c_string(Native.call(:licd_error_detail, ctx_handle)) : ''
+    raise build_error(status, operation, detail)
+  end
+end

data/lib/keynub_licdongle/native.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+# FFI layer: locates the native core and declares the C ABI
+# (SDK/core/include/licdongle.h).
+#
+# Built on Fiddle, which is part of Ruby's standard library, so this binding needs
+# **no gems at all** — not ffi, not a compiled extension. For a licensing library
+# that matters twice: no build toolchain at the customer, and no third-party
+# dependency in the path of the check.
+#
+# The cost is that these signatures are strings no compiler verifies, which is why
+# so every one of them is written out by hand.
+
+require 'fiddle'
+require 'fiddle/import'
+require 'rbconfig'
+
+module KeyNubLicDongle
+  # C struct layouts. Fiddle computes the padding, so the offsets are not
+  # hand-maintained — getting one wrong reads a neighbouring field, and the
+  # symptom is a plausible-looking wrong value rather than a crash.
+  module Types
+    extend Fiddle::Importer
+
+    Info = struct [
+      'unsigned char proto_version_major',
+      'unsigned char proto_version_minor',
+      'unsigned char fw_version_major',
+      'unsigned char fw_version_minor',
+      'unsigned char fw_version_patch',
+      'int se_ready',
+      'int provisioned',
+      'unsigned int data_capacity',
+      'unsigned int data_free',
+      'int watchdog_reboot',
+      'int isolated',
+      'int writeauth_rotated'
+    ]
+
+    GenuineResult = struct [
+      'int genuine',
+      'char serial[15]',
+      'char provisioned_date[11]'
+    ]
+
+    DeviceInfo = struct [
+      'char serial[15]',
+      'char path[512]',
+      'unsigned short vendor_id',
+      'unsigned short product_id'
+    ]
+  end
+
+  # Not part of the public API.
+  module Native
+    BASENAMES = {
+      'mswin' => 'keynub_licdongle.dll',
+      'mingw' => 'keynub_licdongle.dll',
+      'cygwin' => 'keynub_licdongle.dll',
+      'darwin' => 'libkeynub_licdongle.dylib'
+    }.freeze
+
+    def self.default_basename
+      host = RbConfig::CONFIG['host_os']
+      BASENAMES.each { |key, name| return name if host.include?(key) }
+      'libkeynub_licdongle.so'
+    end
+
+    # Where to look, in order. The environment override names a specific library
+    # to point at the simulator library.
+    def self.candidate_paths
+      override = ENV['KEYNUB_LICDONGLE_LIBRARY']
+      return [override] if override && !override.empty?
+
+      here = File.dirname(__FILE__)
+      [
+        File.expand_path(File.join(here, '..', '..', 'vendor', default_basename)),
+        # The prebuilt library a checkout of the SDK carries, per platform: what
+        # makes a clone runnable with nothing set.
+        File.expand_path(File.join(here, '..', '..', '..', '..', 'natives',
+                                   repo_rid, default_basename)),
+        File.expand_path(File.join(here, default_basename)),
+        default_basename # system search path
+      ]
+    end
+
+    # The natives/<rid> directory name for this Ruby.
+    def self.repo_rid
+      host = RbConfig::CONFIG['host_os']
+      os = if host.include?('mswin') || host.include?('mingw') || host.include?('cygwin')
+             'win'
+           elsif host.include?('darwin')
+             'osx'
+           else
+             'linux'
+           end
+      arch = case RbConfig::CONFIG['host_cpu']
+             when 'x86_64', 'x64', 'amd64' then 'x64'
+             when 'i386', 'i486', 'i586', 'i686', 'x86' then 'x86'
+             when 'aarch64', 'arm64' then 'arm64'
+             else 'unknown'
+             end
+      "#{os}-#{arch}"
+    end
+
+    def self.load_library
+      errors = []
+      candidate_paths.each do |path|
+        return Fiddle.dlopen(path)
+      rescue Fiddle::DLError => e
+        errors << "#{path}: #{e.message}"
+      end
+      raise LoadError,
+            "could not load the keynub_licdongle native library; tried:\n  #{errors.join("\n  ")}"
+    end
+
+    LIB = load_library
+
+    INT = Fiddle::TYPE_INT
+    VOIDP = Fiddle::TYPE_VOIDP
+    SIZE_T = Fiddle::TYPE_SIZE_T
+    U32 = Fiddle::TYPE_INT # uint32 by value: int is 32-bit everywhere the SDK runs
+    VOID = Fiddle::TYPE_VOID
+
+    SIGNATURES = {
+      licd_version: [VOID, [VOIDP, VOIDP, VOIDP]],
+      licd_init: [INT, [VOIDP]],
+      licd_free: [VOID, [VOIDP]],
+      licd_set_trust_root: [INT, [VOIDP, VOIDP, SIZE_T]],
+
+      licd_enumerate: [INT, [VOIDP, VOIDP, VOIDP]],
+      licd_free_device_list: [VOID, [VOIDP, SIZE_T]],
+      licd_open: [INT, [VOIDP, VOIDP, VOIDP]],
+      licd_open_path: [INT, [VOIDP, VOIDP, VOIDP]],
+      licd_close: [VOID, [VOIDP]],
+
+      licd_get_info: [INT, [VOIDP, VOIDP]],
+      licd_get_serial: [INT, [VOIDP, VOIDP, SIZE_T]],
+
+      licd_verify_genuine: [INT, [VOIDP, VOIDP]],
+      licd_session_open: [INT, [VOIDP]],
+      licd_session_close: [INT, [VOIDP]],
+      licd_write_auth: [INT, [VOIDP, VOIDP, SIZE_T]],
+      licd_write_auth_rotate: [INT, [VOIDP, VOIDP, SIZE_T]],
+
+      licd_record_list: [INT, [VOIDP, VOIDP, VOIDP, VOIDP]],
+      licd_free_record_list: [VOID, [VOIDP, VOIDP, SIZE_T]],
+      licd_record_read: [INT, [VOIDP, VOIDP, U32, VOIDP, U32, VOIDP, VOIDP, VOIDP, VOIDP]],
+      licd_record_write: [INT, [VOIDP, VOIDP, VOIDP, U32, VOIDP, VOIDP]],
+      licd_record_erase: [INT, [VOIDP, VOIDP]],
+
+      licd_counter_read: [INT, [VOIDP, INT, VOIDP]],
+      licd_counter_increment: [INT, [VOIDP, INT, VOIDP]],
+
+      licd_app_encrypt: [INT, [VOIDP, INT, VOIDP, U32, VOIDP, VOIDP]],
+      licd_app_decrypt: [INT, [VOIDP, VOIDP, U32, VOIDP, VOIDP]],
+      licd_free_buffer: [VOID, [VOIDP]],
+
+      licd_strerror: [VOIDP, [INT]],
+      licd_error_detail: [VOIDP, [VOIDP]]
+    }.freeze
+
+    BOUND = SIGNATURES.each_with_object({}) do |(name, (ret, args)), acc|
+      acc[name] = Fiddle::Function.new(LIB[name.to_s], args, ret, name: name.to_s)
+    end.freeze
+
+    def self.call(name, *args)
+      BOUND.fetch(name).call(*args)
+    end
+
+    # --- marshalling helpers ------------------------------------------------
+
+    PTR_SIZE = Fiddle::SIZEOF_VOIDP
+    SIZE_T_SIZE = Fiddle::SIZEOF_SIZE_T
+    SIZE_T_PACK = SIZE_T_SIZE == 8 ? 'Q' : 'L'
+
+    # A writable buffer, freed by Ruby's GC.
+    def self.buffer(size)
+      Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
+    end
+
+    def self.out_pointer
+      buffer(PTR_SIZE)
+    end
+
+    def self.out_int32
+      buffer(4)
+    end
+
+    def self.out_size_t
+      buffer(SIZE_T_SIZE)
+    end
+
+    def self.read_int32(pointer)
+      pointer[0, 4].unpack1('l')
+    end
+
+    def self.read_uint32(pointer)
+      pointer[0, 4].unpack1('L')
+    end
+
+    def self.read_size_t(pointer)
+      pointer[0, SIZE_T_SIZE].unpack1(SIZE_T_PACK)
+    end
+
+    # A NUL-terminated string out of a fixed-size buffer we own.
+    def self.read_fixed_string(bytes)
+      nul = bytes.index("\0")
+      (nul ? bytes[0, nul] : bytes).dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # A NUL-terminated string from a `char *` the library owns.
+    def self.read_c_string(address)
+      value = address.respond_to?(:to_i) ? address.to_i : address
+      return '' if value.zero?
+
+      Fiddle::Pointer.new(value).to_s.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # Copies `length` bytes out of a library-allocated buffer, then frees it.
+    def self.take_buffer(out_ptr, length)
+      address = out_ptr.ptr
+      return String.new(encoding: Encoding::BINARY) if address.to_i.zero? || length.zero?
+
+      begin
+        # A pointer read out of another pointer has no size of its own; tell Fiddle
+        # how much is really there so the read is in bounds.
+        address.size = length
+        address[0, length].dup.force_encoding(Encoding::BINARY)
+      ensure
+        call(:licd_free_buffer, address)
+      end
+    end
+
+    # A NUL-terminated C string Fiddle can pass, or NULL for nil.
+    def self.c_string(value)
+      return nil if value.nil?
+
+      "#{value}\0"
+    end
+  end
+end

data/lib/keynub_licdongle/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module KeyNubLicDongle
+  # The binding's version. Tracks the SDK's; the native core reports its own via
+  # KeyNubLicDongle::Context.library_version.
+  VERSION = '1.1.1'
+end

data/lib/keynub_licdongle.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+
+# KeyNub License Dongle — Ruby binding.
+#
+#   require 'keynub_licdongle'
+#
+#   KeyNubLicDongle::Context.open do |ctx|
+#     dongle = ctx.open              # first dongle, or ctx.open(serial)
+#     dongle.verify_genuine!         # raises unless genuine
+#     dongle.session do |session|
+#       data = session.app_decrypt(blob)   # <- build the licence check on this
+#     end
+#   end
+#
+# No gems: the FFI layer is Ruby's own Fiddle. Every call is synchronous — a
+# dongle round trip is a millisecond or two of USB HID.
+#
+# Read docs/integration-security.md before deciding where the check goes.
+# `exit unless licensed?` is one line to delete, and Ruby ships as source. What
+# cannot be deleted is data the program needs and only the dongle can decrypt.
+
+require_relative 'keynub_licdongle/version'
+require_relative 'keynub_licdongle/native'
+require_relative 'keynub_licdongle/errors'
+
+module KeyNubLicDongle
+  # Who can decrypt data produced by Session#app_encrypt.
+  module Scope
+    DEVICE = 0    # only this one physical dongle
+    DEVELOPER = 1 # any dongle issued by the same developer
+    ALL = [DEVICE, DEVELOPER].freeze
+  end
+
+  SERIAL_BUFFER = 15 # LICD_SERIAL_HEX_LEN + 1
+  private_constant :SERIAL_BUFFER
+
+  # The library context: the entry point for finding and opening dongles.
+  class Context
+    # Yields a context and closes it afterwards, whatever happens.
+    def self.open
+      ctx = new
+      begin
+        yield ctx
+      ensure
+        ctx.close
+      end
+    end
+
+    # The native core's version, as [major, minor, patch].
+    def self.library_version
+      parts = Array.new(3) { Native.out_int32 }
+      Native.call(:licd_version, *parts)
+      parts.map { |p| Native.read_int32(p) }
+    end
+
+    def initialize
+      out = Native.out_pointer
+      KeyNubLicDongle.check(Native.call(:licd_init, out), 'licd_init')
+      @handle = out.ptr
+      @closed = false
+    end
+
+    def closed?
+      @closed
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      Native.call(:licd_free, @handle)
+      @handle = nil
+    end
+
+    # The raw handle, for mixing this binding with direct Fiddle calls.
+    def handle
+      raise Error.new(Status::INVALID_ARGUMENT, 'the context has been closed') if @closed
+
+      @handle
+    end
+
+    # The SDK's diagnostic detail for the most recent failure on this thread.
+    def last_error_detail
+      Native.read_c_string(Native.call(:licd_error_detail, handle))
+    end
+
+    # Overrides the CA root that Dongle#verify_genuine checks against.
+    #
+    # Applications do not need this: a release build embeds the KeyNub production
+    # root. It exists for dongles provisioned against a different CA, and for
+    # vendor tooling.
+    def trust_root=(der)
+      bytes = der.to_s.b
+      check(Native.call(:licd_set_trust_root, handle, bytes, bytes.bytesize),
+            'licd_set_trust_root')
+    end
+
+    # Connected dongles, as an array of hashes. Empty when none are attached,
+    # which is a normal result rather than an error.
+    def enumerate
+      list = Native.out_pointer
+      count_ptr = Native.out_size_t
+      check(Native.call(:licd_enumerate, handle, list, count_ptr), 'licd_enumerate')
+      count = Native.read_size_t(count_ptr)
+      base = list.ptr
+      return [] if count.zero? || base.to_i.zero?
+
+      begin
+        stride = Types::DeviceInfo.size
+        Array.new(count) do |i|
+          entry = Types::DeviceInfo.new(base + (i * stride))
+          {
+            serial: Native.read_fixed_string(entry.serial.pack('c*')),
+            path: Native.read_fixed_string(entry.path.pack('c*')),
+            vendor_id: entry.vendor_id,
+            product_id: entry.product_id
+          }
+        end
+      ensure
+        Native.call(:licd_free_device_list, base, count)
+      end
+    end
+
+    # Opens the dongle with this serial, or the first one found.
+    def open(serial = nil)
+      out = Native.out_pointer
+      check(Native.call(:licd_open, handle, Native.c_string(serial), out), 'licd_open')
+      Dongle.new(self, out.ptr)
+    end
+
+    # Opens a specific dongle by the +:path+ from #enumerate.
+    def open_path(path)
+      out = Native.out_pointer
+      check(Native.call(:licd_open_path, handle, Native.c_string(path), out), 'licd_open_path')
+      Dongle.new(self, out.ptr)
+    end
+
+    # Adopts a device opened through the C ABI directly. Lets this binding be
+    # introduced into existing Fiddle code a call at a time, and is how the test
+    # harness wraps a simulated device.
+    def adopt(device_handle)
+      Dongle.new(self, device_handle)
+    end
+
+    def check(status, operation) # :nodoc:
+      KeyNubLicDongle.check(status, operation, @closed ? nil : @handle)
+    end
+  end
+
+  # An open connection to a dongle. Plaintext operations here; stored data needs
+  # a Session.
+  class Dongle
+    def initialize(context, handle)
+      @context = context
+      @handle = handle
+      @closed = false
+    end
+
+    attr_reader :context
+
+    def closed?
+      @closed
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      Native.call(:licd_close, @handle)
+      @handle = nil
+    end
+
+    def handle
+      raise Error.new(Status::INVALID_ARGUMENT, 'the dongle has been closed') if @closed
+
+      @handle
+    end
+
+    # Plaintext device info, as a hash.
+    #
+    # +:watchdog_reboot+ reports that the dongle's *previous* boot ended in a
+    # watchdog timeout — the firmware hung and reset itself. It is the only trace
+    # a field hang leaves behind, and a power cycle clears it, so log it.
+    #
+    # +:isolated+ reports that the dongle confirmed at boot that its USB and parsing code is fenced off
+    # from keys and storage. Anything that is not a dongle reports false.
+    def info
+      raw = Types::Info.malloc(Fiddle::RUBY_FREE)
+      @context.check(Native.call(:licd_get_info, handle, raw), 'licd_get_info')
+      {
+        protocol_version: [raw.proto_version_major, raw.proto_version_minor],
+        firmware_version: [raw.fw_version_major, raw.fw_version_minor, raw.fw_version_patch],
+        se_ready: !raw.se_ready.zero?,
+        provisioned: !raw.provisioned.zero?,
+        data_capacity: raw.data_capacity,
+        data_free: raw.data_free,
+        watchdog_reboot: !raw.watchdog_reboot.zero?,
+        isolated: !raw.isolated.zero?,
+        writeauth_rotated: !raw.writeauth_rotated.zero?
+      }
+    end
+
+    # The dongle serial as hex.
+    def serial
+      buffer = Native.buffer(SERIAL_BUFFER)
+      @context.check(Native.call(:licd_get_serial, handle, buffer, SERIAL_BUFFER),
+                     'licd_get_serial')
+      Native.read_fixed_string(buffer[0, SERIAL_BUFFER])
+    end
+
+    # Proves authenticity: the certificate chain to the trusted root plus a live
+    # ECDSA challenge-response. Raises unless the dongle is genuine.
+    def verify_genuine!
+      raw = Types::GenuineResult.malloc(Fiddle::RUBY_FREE)
+      @context.check(Native.call(:licd_verify_genuine, handle, raw), 'licd_verify_genuine')
+      {
+        genuine: !raw.genuine.zero?,
+        serial: Native.read_fixed_string(raw.serial.pack('c*')),
+        provisioned_date: Native.read_fixed_string(raw.provisioned_date.pack('c*'))
+      }
+    end
+
+    # The non-raising form, for a licence gate. Fails closed: a missing dongle, an
+    # I/O error and an invalid certificate all return false.
+    def genuine?
+      verify_genuine![:genuine]
+    rescue Error
+      false
+    end
+
+    # Opens an encrypted session (P-256 ECDH, HKDF-SHA256, AES-256-GCM). With a
+    # block, closes it afterwards.
+    def session
+      @context.check(Native.call(:licd_session_open, handle), 'licd_session_open')
+      session = Session.new(self)
+      return session unless block_given?
+
+      begin
+        yield session
+      ensure
+        session.close
+      end
+    end
+    alias open_session session
+  end
+
+  # An open encrypted session: records, counters and app-crypto.
+  class Session
+    def initialize(dongle)
+      @dongle = dongle
+      @closed = false
+    end
+
+    def closed?
+      @closed
+    end
+
+    # Ends the session, zeroizing the session keys on the dongle. Never raises:
+    # teardown is local state, and this runs from ensure blocks.
+    def close
+      return if @closed
+
+      @closed = true
+      Native.call(:licd_session_close, @dongle.handle) unless @dongle.closed?
+    end
+
+    # Elevates to the write role with the developer master key (a DER EC private
+    # key). This belongs in your licence-issuing tooling; never ship
+    # that key in the application your users run.
+    def authorize_write(master_key_der)
+      bytes = master_key_der.to_s.b
+      check(Native.call(:licd_write_auth, device, bytes, bytes.bytesize), 'licd_write_auth')
+    end
+
+    # Replaces the dongle's write-auth key with your own (a DER EC private key).
+    # Call authorize_write with the current key first. From the next session on,
+    # only the new key elevates.
+    def rotate_write_key(new_key_der)
+      bytes = new_key_der.to_s.b
+      check(Native.call(:licd_write_auth_rotate, device, bytes, bytes.bytesize),
+            'licd_write_auth_rotate')
+    end
+
+    # Records stored on the dongle, as an array of {name:, size:} hashes.
+    def list_records
+      names = Native.out_pointer
+      sizes = Native.out_pointer
+      count_ptr = Native.out_size_t
+      check(Native.call(:licd_record_list, device, names, sizes, count_ptr), 'licd_record_list')
+      count = Native.read_size_t(count_ptr)
+      name_base = names.ptr
+      size_base = sizes.ptr
+      return [] if count.zero? || name_base.to_i.zero?
+
+      begin
+        Array.new(count) do |i|
+          name_ptr = name_base[i * Native::PTR_SIZE, Native::PTR_SIZE].unpack1(Native::SIZE_T_PACK)
+          {
+            name: Native.read_c_string(name_ptr),
+            size: size_base[i * 4, 4].unpack1('L')
+          }
+        end
+      ensure
+        Native.call(:licd_free_record_list, name_base, size_base, count)
+      end
+    end
+
+    # Reads a record. A block is called as +progress(done, total)+; return false
+    # from it to cancel, which raises OperationCancelledError.
+    def read_record(name, &progress)
+      require_name(name)
+      cname = Native.c_string(name)
+
+      # Probe for the size first, so progress runs monotonically from 0 to total.
+      got = Native.out_int32
+      total = Native.out_int32
+      probe = Native.buffer(1)
+      check(Native.call(:licd_record_read, device, cname, 0, probe, 1, got, total, nil, nil),
+            'licd_record_read')
+      size = Native.read_uint32(total)
+      return String.new(encoding: Encoding::BINARY) if size.zero?
+
+      buffer = Native.buffer(size)
+      status = with_progress(progress) do |callback|
+        Native.call(:licd_record_read, device, cname, 0, buffer, size, got, total, callback, nil)
+      end
+      check(status, 'licd_record_read')
+      buffer[0, Native.read_uint32(got)].dup.force_encoding(Encoding::BINARY)
+    end
+
+    # Atomically replaces a record. Requires the write role.
+    def write_record(name, data, &progress)
+      require_name(name)
+      bytes = data.to_s.b
+      status = with_progress(progress) do |callback|
+        Native.call(:licd_record_write, device, Native.c_string(name), bytes, bytes.bytesize,
+                    callback, nil)
+      end
+      check(status, 'licd_record_write')
+      nil
+    end
+
+    # Erases one record. Requires the write role.
+    def erase_record(name)
+      # A nil name means "erase everything" to the C API; that is #erase_all_records
+      # here, so an empty string cannot wipe the dongle.
+      require_name(name)
+      check(Native.call(:licd_record_erase, device, Native.c_string(name)), 'licd_record_erase')
+    end
+
+    # Erases every record. Requires the write role.
+    def erase_all_records
+      check(Native.call(:licd_record_erase, device, nil), 'licd_record_erase')
+    end
+
+    # Reads a hardware monotonic counter.
+    def read_counter(counter_id)
+      value = Native.out_int32
+      check(Native.call(:licd_counter_read, device, counter_id, value), 'licd_counter_read')
+      Native.read_uint32(value)
+    end
+
+    # Increments a counter and returns the new value. Irreversible: the counter is
+    # monotonic in hardware. Requires the write role.
+    def increment_counter(counter_id)
+      value = Native.out_int32
+      check(Native.call(:licd_counter_increment, device, counter_id, value),
+            'licd_counter_increment')
+      Native.read_uint32(value)
+    end
+
+    # Encrypts so that only a dongle of +scope+ can decrypt.
+    #
+    # This is the pair to build a licence check on: put something the program
+    # genuinely needs through it, so removing the check removes the data.
+    def app_encrypt(scope, plaintext)
+      unless Scope::ALL.include?(scope)
+        raise ArgumentError, "scope must be Scope::DEVICE or Scope::DEVELOPER, got #{scope.inspect}"
+      end
+
+      bytes = plaintext.to_s.b
+      out = Native.out_pointer
+      out_len = Native.out_int32
+      check(Native.call(:licd_app_encrypt, device, scope, bytes, bytes.bytesize, out, out_len),
+            'licd_app_encrypt')
+      Native.take_buffer(out, Native.read_uint32(out_len))
+    end
+
+    # Decrypts a blob produced by #app_encrypt, using the dongle.
+    def app_decrypt(packed)
+      bytes = packed.to_s.b
+      out = Native.out_pointer
+      out_len = Native.out_int32
+      check(Native.call(:licd_app_decrypt, device, bytes, bytes.bytesize, out, out_len),
+            'licd_app_decrypt')
+      Native.take_buffer(out, Native.read_uint32(out_len))
+    end
+
+    private
+
+    def device
+      raise SessionExpiredError.new(Status::SESSION_EXPIRED, 'the session has been closed') if @closed
+
+      @dongle.handle
+    end
+
+    def check(status, operation)
+      @dongle.context.check(status, operation)
+    end
+
+    def require_name(name)
+      return unless name.nil? || name.to_s.empty?
+
+      raise ArgumentError, 'the record name must not be empty'
+    end
+
+    # Wraps a Ruby block as a C progress callback and returns the native status.
+    #
+    # An exception raised inside the block is held until the SDK has unwound its
+    # own transfer, then re-raised: letting it escape through the C frames would
+    # skip that cleanup and strand the device mid-transfer. It takes precedence
+    # over the resulting LICD_E_CANCELLED, because the callback's failure is the
+    # cause and the cancellation is only its consequence.
+    def with_progress(progress)
+      return yield(nil) if progress.nil?
+
+      raised = nil
+      callback = Fiddle::Closure::BlockCaller.new(
+        Fiddle::TYPE_INT, [Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP]
+      ) do |done, total, _user|
+        if raised
+          0
+        else
+          begin
+            # Anything but an explicit false continues, so a callback that only
+            # draws a progress bar is safe.
+            progress.call(done, total) == false ? 0 : 1
+          rescue StandardError => e
+            raised = e
+            0
+          end
+        end
+      end
+
+      # Held in an ivar, not just a local, so the closure cannot be collected while
+      # C holds a pointer to it.
+      @active_callback = callback
+      begin
+        status = yield(callback)
+        raise raised if raised
+
+        status
+      ensure
+        @active_callback = nil
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: keynub_licdongle
+version: !ruby/object:Gem::Version
+  version: 1.1.1
+platform: ruby
+authors:
+- KeyNub
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-12 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Talks to a KeyNub USB-C license dongle: authenticity verification, an
+  encrypted session, licence records, monotonic counters, and envelope
+  encryption bound to the dongle. Built on Fiddle from Ruby's standard library,
+  so it needs no gems and no compiler.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- BINARY-LICENSE.txt
+- LICENSE
+- NOTICE
+- README.md
+- THIRD-PARTY-NOTICES.txt
+- lib/keynub_licdongle.rb
+- lib/keynub_licdongle/errors.rb
+- lib/keynub_licdongle/native.rb
+- lib/keynub_licdongle/version.rb
+homepage: https://www.keynub.com/developers/ruby/
+licenses:
+- Apache-2.0
+- LicenseRef-KeyNub-Binary
+metadata:
+  homepage_uri: https://www.keynub.com/developers/ruby/
+  source_code_uri: https://github.com/AB-KeyNub/KeyNub-SDK
+  documentation_uri: https://github.com/AB-KeyNub/KeyNub-SDK/blob/master/bindings/ruby/README.md
+  bug_tracker_uri: https://github.com/AB-KeyNub/KeyNub-SDK/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby binding for the KeyNub USB-C license dongle
+test_files: []