Software protection guide

Software protection with the KoalaKey is created using the KoalaKey Scripter:

Layout of the Software protection tool

The output of this script is loaded into a license module on the KoalaKey via a .KKscript file using GumTree, up to 256 can be loaded at any time and the operation of these scripts are run completely independently of the OS. Each module has a command size limit of 512 bytes where different commands have different sizes. Up to 256 pages of persistent data can be stored (or 131kb of data). KoalaKey has an internal “infinite loop” detector which is triggered if the script is run for 100,000,000 commands. Please note that whilst the KoalaKey can support lengthy commands, it will adversely effect performance, for example during mass storage file transfers. An ideal length is less then 5000 commands. If an operation is to be longer, please use multiple calls.

When trying to run one of these scripts, call the license module set to run the operations loaded. Up to 40 bytes of data can be sent and received in a single call. Saving and loading persistent data is the most time expensive operation and should be used sparingly.

  1. Data input is located in positions 0~9
  2. Data to return back to the software is located in 10~19
  3. RAM (data that is lost/set to 0 on execution end) is located 20~127
  4. Persistent data is located 128~255, if this is not loaded, all 0

Vanilla javascript and HTML was used in the creation of this tool with no PHP/server side operation, please feel free to download the tool via your browser for use offline. A syntactical tool to convert C code is planned for the future.

The URL of the script can store the commands and persistent memory for ease of development.

To do list for SP tool:
1. Autosave via cookies periodically, toggle-able feature?
2. Step through commands via highlighting, useful for debugging loops
3. Fold-unfold command list, exportable sub-sections?
4. Incrementing CMD pointers when inserting above

Here are a list of example scripts:

General examples:

1. Simple goto loop and increment value
This forms a loop between commands 2 and 5 until location 21 has a value of 5
a) Sets a value of 5 in position 20
b) Increment the value located at 21 (from 0 to 1)
c) If location 22 has a value of 1, goto command 2 (loops)
Simple loop using goto
2. Consuming and returning input and output
a) Takes input for position 0, this is done with the inputs underneath the commands list
b) Increment position 0 (or input 0)
c) Sets a value to multiply it with
d) gives output from position 0 and multiplication result by placing the result in positions 10 and 11

3. Random number generator (LFSR)
Implements the C LFSR example from wikipedia:
LFSR example from Wikipedia
This script demonstrates how existing C code can be converted into KKscript, this C code example finds the period of an LFSR with specific tap points, this is how many unique bits the LSFR will output before repeating itself. Expected result from the example is a period of 65535 or 2^16-1 and is the maximum size of uint16_t.
a) Initialize variables start_state, period, lfsr and a bitmask for handling overflow (commands 1~4).
a.1) period is set as 0 to output 10 (note that this is not needed since RAM is set to 0 on startup)
a.2) start_state is stored in position 20, 0xACE1 = 44257
a.3) lfsr is used as the state of the RNG at position 21
a.4) to prevent overflow bits, a mask of 0x0000ffff is used, the software protection tool operates in uint32_t and will overflow in this example as it expects a maximum size of uint_16.
b) Perform lfsr bitwise operations (commands 5~11)
c) Increment period counter
d) Compare state of lfsr with the initial state, if it is different, go back to command 5, this is equivalent to the while loop

Bitwise operations are broken down in order of operation. For example lfsr ^= lfsr >> 7; is equivalent to:
lfsr = lfsr XOR (lfsr RightShift 7);

However KoalaKey can only handle one operation at a time, so it is broken down like this:

temp = lfsr RightShift 7; //command 5, POS 23 = POS 21 >> 7
lfsr = lfsr XOR temp; //command 6, POS 21 = POS 21 XOR POS 23

Note that a bitwise mask is used for the operation lfsr << 9, as that will cause an overflow on command 8.

4. Set license module with simple password
a) Pre-set an example password of 1234
b) If the expected value (1234) is given as Input 0, proceed to set the license module, otherwise attempt to decrement license
c) To set license module, this loads a value of 10 to position 128, then save consistent memory to page 0
This demonstrates saving/loading data to the persistent memory of the KoalaKey, this simple password to authenticate as license administrator is not intended for real use, please use a more robust method of determining if the set license operation is authorized.
Please use "Run All" multiple times to see how this script operates.
5. OATH compliant HOTP Generator
This is an example of how to use the KoalaKey in as an OATH compliant HOTP generator as specified by RFC 4226. The example will generate the same OTP's as the default loaded HOTP on PIN 2. This example also demonstrates the use of SHA1 and dynamically addressing data stored on the KoalaKey and some logic handling for dynamic positions.
HOTP process in KK script example
C code equivalent for example KK script

6. HSM like API package:
This is a set of scripts that emulate the behaviour of similar hardware token’s API with KoalaKey.
Selecting the command to use is based on a set of defines within your program via input 0, currently provided in this example:

  • 0-CMD 29: Get hardware ID of KK: tool has hardcoded HID of: 1286608618
  • 1-CMD 31: Get token ID of KK: tool has hardcoded token ID of: 1234567890
  • 2-CMD 33: Get name of KK: MyKoalaKeyNamethatIs30CharLong
  • 3-CMD 35: Get and Decrement a license module as specified in input 1, 10 modules are provided
  • 4-CMD 35: Get value of a license module as specified in input 1
  • 5-CMD 113: Set a license module as specified in input 2, 10 modules are provided. Example password is: 12345 which must be passed with input 3.
    • Set license:
      • 5 1 2 12345
      • Command 5 (set license) for license module 1, to a starting value 2, authkey 12345
    • Get and decrement license:
      • 3 1
      • Command 3, get and decrement license 1
      • Get and decrement license:
    • Read value of license module:
      • 4 1
      • Command 4, read license 1

This example will be added upon with time, for example encrypt decrypt, set encryption key with a seed value etc.
There are some known issues, for example re-running the get license will return HID

Powered by BetterDocs