afAxonEncryptorExt

Protect your Intellectual Property with Axon Encryptor.

You may not realise that distributing Axon functions to clients and customers in .pod files and plain text Trio files, means anyone can copy / paste your Axon code and potentially steal your hard work!

The good news is that Axon Encryptor obfuscates and protects your Intellectual Property with source code encryption!

When your code is received at the other end, the encryption stays in place while the code is executed by our free runtime library - afAxonEncryptorRtExt.

Combine this functionality with a StackHub License and you can also restrict where and when your Axon code can be run.

Axon Encryptor is FREE to download and evaluate but a licence must be purchased for production use. See Licensing for details.

Contents

• Overview
• Quick Start
• Encrypt via... Pod Builder
• Encrypt via... Axon
• Encrypt via... Cmd Line
• Encrypt via... Fantom Build Task
• What are Runtime Keys?
• What are Key Funcs?
  • Custom KeyFuncs
  • StackHub KeyFuncs
• Distributing encrypted functions
  • Resource Pods
  • Fantom Pods
• FAQs
  • Q. How do I see the decrypted Axon source code?
  • Q. Does Axon Encryptor impact on function performance?
  • Q. Are 'defcomp' functions supported?
  • Q. How do I avoid encrypting an Axon function?
• Notes on Security
• Licensing
  • Evaluation mode
• Disclaimer

Overview

Axon Encryptor takes your plain text Axon source code along with a pass phrase, and generates encrypted Axon code that can only be executed with a runtime key.

For example, this plain text Axon source code:

(name) => do
  return "Hello " + name + "!"
end

becomes this encrypted source code:

(name) => do
  cipherText :
    "AxD:mvUjtIFWCMNZV1HuOAxMMg::jc84ZwXVBPzw3vfg2rLl1NIZx8eemoG_pYZEnnZfSvYZElURNjU4" +
    "c62cfYTMHGMf2HFsjYn0V8Kagb8hj8nBN9lkRUryYUxojI6zuWCnNef1LIqJ7fDdwcC43dpXsMunsHH_" +
    "6U7eKhTxJWzF0A32SLsdnotcjOwOyRKfUI91n-QHma9mEi2Ri4mRhGW805ISTU5Ut_LiwdImXL-qnqHQ" +
    "FUuWwiV-53ZSFnyUi_uAybEJBxNbiFiSRSptuTsrO5SQd6Np2V4iGM25b0Rc_WRP09LYbuo4Qo0w_Dqu" +
    "hvpRSpzGJzo1nBrEKtViI3T9j6R3RLTkXkwi8Jqp6kuJhjERyQ"
  keyFunc : () => "ddJNIRm2qio2Z7CXpKADiw"
  return afAxonEncryptorRt_callFunc("hello", cipherText, [name], keyFunc)
end

Axon Encryptor can be used on:

• an individual function or component record,
• a Trio file of functions and components,
• an entire directory of Trio files,
• or even an entire pre-compiled pod!

Axon Encryptor never reveals the original Axon source so you can be confident your intellectual property remains safe. Instead, we provide an Axon Encryptor Runtime library which uses the runtime key to execute the obfuscated code - without exposing the original source.

The encrypted functions and Trio files are direct drop-in replacements for the original source. So if you are distributing your Axon functions via .pod files, encrypt your Axon source files and distribute the encrypted version in place of the originals.

Axon Encryptor is a SkySpark extension requiring SkySpark v3.1.1 (or later). For older v3.0.x versions of SkySpark, download Axonator v1.0.

Quick Start

Use the Axon Encryptor App to encrypt individual functions.

Copy / paste your Axon source code into the box on the left, click "Encrypt", and the encrypted Axon source code appears on the right.

Use the "Settings" dialogue to change the Pass Phrase, Key Func, and more.

Encrypt via... Pod Builder

Pod Builder is another available tool which lets you create SkySpark extensions with ease, compiling Axon functions and Folio records into SkySpark .pod files.

If Pod Builder and Axon Encryptor are enabled in the same SkySpark project, they work seamlessly together, encrypting your Axon functions as part of the Pod Building process.

All Axon encryption settings may be changed on a per-pod basis.

Encrypt via... Axon

Axon Encryptor provides a couple of Axon functions to automate the encryption process.

• afAxonEncryptor_encryptFunc(funcRec, passPhrase) - encrypts an Axon function record
• afAxonEncryptor_encryptTrioFile(trioFile, outputDir, passPhrase) - encrypts a Trio file on the file system

An example of how to encrypt an Axon function record:

// Axon function records are normally created with the Code app
// but here we're going to create one programmatically
plainFuncRec : {
    func,
    "name" : "hello",
    "src"  : """(name) => "Hello " + name + "!" """
}

// encrypt the function
passPhrase : "Axon Encryptor Protects"
encrypted  : afAxonEncryptor_encryptFunc(plainFuncRec, passPhrase)

// this is the encrypted func record
encryptedFuncRec : encrypted["funcRec"]

// print the encrypted Axon source to the console
echo( encryptedFuncRec["src"] )

The returned encrypted function may be run just like any other Axon function:

// compile the encrypted func...
helloFn : encryptedFuncRec["src"].eval()

// ...and run it!
helloFn("Mum")  // --> "Hello Mum!"

Encrypt via... Cmd Line

Axon Encryptor may be invoked from the command line to encrypt .trio files and .pod files as a whole. This is useful if you wish to encrypt functions in a non-SkySpark environment.

The examples below have new lines and whitespace added for clarity.

fan afAxonEncryptorExt
    -input        lib/myFuncs.trio
    -outputDir    build/
    -passPhrase   "Axon Encryptor Protects"
    -skysparkLic  lic/lic-skyspark.props
    -encryptorLic lic/lic-axonEncryptor.props

-input may be a single .trio file, a directory of .trio files, or a .pod file. If a pod file, then all .trio files inside are scanned for functions and encrypted in the usual way.

To use Axon Encryptor in evaluation mode, just omit the licences:

fan afAxonEncryptorExt
    -input       lib/myFuncs.trio
    -outputDir   build/
    -passPhrase  "Axon Encryptor Protects"

Note for Windows users: You should also use /forward slashes/ in directory names, as per the examples above.

Use the -help option for details:

fan afAxonEncryptorExt -help

Encrypt via... Fantom Build Task

Axon Encryptor contains a Fantom Build Task class enabling more advanced users to encrypt Axon functions as part of their Fantom pod build process.

In your pod's build script add a target like this:

@Target { help = "Encrypt all Axon functions found in .trio files" }
Void encrypt() {
    task := afAxonEncryptorExt::AxonEncryptorTask(this)
    task.passPhrase   = "Who you gonna call?"
    task.skysparkLic  = `lic/lic-skyspark.props`.toFile
    task.encryptorLic = `lic/lic-axonEncryptor.props`.toFile
    task.run
}

Which you can run from the command line like this:

fan build.fan encrypt

What are Runtime Keys?

A runtimeKey is required to execute encrypted functions.

Runtime Keys MUST be generated by Axon Encryptor.

Creating a Runtime Key by any other means will result in an Invalid Cipher or Runtime Key Error when attempting to execute the encrypted function.

Runtime Keys are created from a given Pass Phrase.

A Pass Phrase is any string that you, the user, create. It is passed to Axon Encryptor during the encryption process, and from this the Runtime Key is generated.

So if you change the Pass Phrase, the Runtime Key also changes.

To recap, you create a Pass Phrase and give it to Axon Encryptor. Axon Encryptor then creates and returns a Runtime Key during the encryption process. This Runtime Key is needed to run the encrypted functions.

This extra step of creating Runtime Keys from Pass Phrases prevents malicious users from encrypting their own functions and having them masquerade as yours.

What are Key Funcs?

It is the job of the keyFunc, when run, to return the runtimeKey.

The default keyFunc just returns the runtimeKey in plain text; as seen in the Overview example.

keyFunc : () => "ddJNIRm2qio2Z7CXpKADiw"

This is usually good enough for most use cases; but if you want to be extra secure, you can hide the runtimeKey elsewhere and use a custom keyFunc to retrieve it.

Custom KeyFuncs

Axon Encryptor lets you use your own keyFunc code to look up or otherwise retrieve the runtimeKey in a more secure fashion.

This allows for highly customisable keyFuncs that are able to retrieve the runtimeKey from a REST API, a secret store, or anywhere!

To use a custom keyFunc, pass its source code (string) to one of the encryption functions. keyFuncs take the function name as an optional argument.

funcRec    : ...
keyFunc    : "(fnName) => lookUpRuntimeKey(fnName)"
passPhrase : "Axon Encryptor Protects"
encrypted  : afAxonEncryptor_encryptFunc(plainFuncRec, passPhrase, keyFunc)

To customise keyFuncs on an individual function basis, an Axon function may be passed to the encryption functions. These keyFunc functions are passed the name of the function being encrypted AND the runtimeKey, and must return a string representing the final keyFunc code.

funcRec    : ...
keyFunc    : (fnName, runtimeKey) => "() => lookUpRuntimeKey(\"" + fnName + "\")"
passPhrase : "Axon Encryptor Protects"
encrypted  : afAxonEncryptor_encryptFunc(plainFuncRec, passPhrase, keyFunc)

StackHub KeyFuncs

The runtimeKey may be stored in a StackHub licence file. This keeps the runtimeKey in a single place separate to the code that needs it.

Moreover, the runtimeKey can only be retrieved if the StackHub licence is valid. Common StackHub licence restrictions include limiting its use to specific SkySpark instances, and / or expiry dates.

This means only people with a valid StackHub generated licence have access to the runtime key, and so only people with a valid StackHub generated licence can run your Axon functions.

This puts you in control of when and who is able to execute your Axon code.

To do this, use afAxonEncryptor_stackhubKeyFunc() to create a keyFunc, passing in the name and version of the pod / package being encrypted.

funcRec    : ...
keyFunc    : afAxonEncryptor_stackhubKeyFunc("acmeMyPackage 1.0")
passPhrase : "Axon Encryptor Protects"
encrypted  : afAxonEncryptor_encryptFunc(plainFuncRec, passPhrase, keyFunc)

Make sure to add the runtimeKey to your StackHub licence file by adding the following extra property to your StackHub product. Which, in our example, would be:

runtimeKey = ddJNIRm2qio2Z7CXpKADiw

Functions encrypted with the above keyFunc are unrestricted, making Axon Encryptor FREE for use with StackHub products. But note, StackHub itself does charge for generating such licences.

Distributing encrypted functions

Encrypted Axon functions have an implicit dependency on the Axon Encryptor Runtime extension. This is required to execute any encrypted Axon functions.

Axon Encryptor Runtime is free and does not require a licence file to use. A valid licence file is only required during encryption to create unrestricted encrypted functions.

When distributing Axon functions via .pod files, some configuration is required to ensure the Axon Encryptor Runtime has been installed and enabled on any target projects.

Note: If creating resource pods via Pod Builder, this configuration is added automatically.

Talk to us if you would like to licence the runtime code to use in your own pods, and remove the dependency on afAxonEncryptorRtExt.

Resource Pods

If your .pod only contains Axon functions and other resources (and has no Fantom code) then add the following lines to your meta.props file:

...
pod.depends=afAxonEncryptorRtExt 2.0.6-2
ext.depends=afAxonEncryptorRt
...

If your meta.props already defines these properties, then the Axon Encryptor Runtime may be appended like this:

...
pod.depends=sys 1.0; afAxonEncryptorRtExt 2.0.6-2
ext.depends=weather, afAxonEncryptorRt
...

Note how one property separates values with a semi-colon and the other with a comma.

pod.depends lets the SkySpark Install Manager know it should download and install Axon Encryptor Runtime along with your extension.

ext.depends lets the SkySpark Extension Manager know it should enable Axon Encryptor Runtime in projects when it enables your extension.

See Resource Extensions in the SkySpark documentation for details.

Fantom Pods

If you are distributing your functions in a Fantom .pod file then your build.fan should express a dependency on afAxonEncryptorRtExt. This will make sure Axon Encryptor Runtime is installed on any target system. It also lets SkySpark Install Manager know it should download and install Axon Encryptor Runtime automatically along with your extension.

depends = [
    // ---- Fantom Core ----
    "sys           1.0.77 - 1.0",

    // ---- Axon Encryptor ----
    "afAxonEncryptorRtExt 2.0.6 - 2",

    // ---- SkySpark ----
    "skyarcd       3.1.1  - 3.0",
    "haystack      3.1.1  - 3.0",
    "stackhub      3.1.1  - 3.0",
    ...
    ...
]

Your extension should also express a dependency on the afAxonEncryptorRt extension to make sure Axon Encryptor Runtime is enabled in projects.

using skyarcd::Ext
using skyarcd::ExtMeta

@ExtMeta {
    name    = "acmeAwesome";
    depends = Str["afAxonEncryptorRt"]
}
const class AwesomeExt : Ext {
  ...
}

FAQs

Q. How do I see the decrypted Axon source code?

You cannot - there is no decryptor! Axon Encryptor never reveals the original Axon source. To do so represents a security risk.

Make sure you keep your source backed up!

Q. Does Axon Encryptor impact on function performance?

The performance impact of using Axon Encryptor should be negligible.

There may be a very small delay the first time an encrypted function is called due to the runtime and compilation process, but once processed, this compiled function is cached for future use.

All subsequent invocations are routed through the cached function, so any performance hit (however slight) is only ever taken once; after that, your function performs just as fast as any un-encrypted version.

For large Axon functions, consider using the multiLineCipher option to generate a single "multiLine" Axon string of cipher text. This improves run time of the encrypted function, but requires the end-user / client to have at least v2.0.6 of the runtime library (afAxonEncryptorRtExt).

Q. Are defcomp functions supported?

Yes! As of Axon Encryptor v2.0.6, Axon components (defcomp functions) may also be encrypted. This allows you to encrypt SkySpark Spark Rules and Cur Rules the same as any other Axon function.

Q. How do I avoid encrypting an Axon function?

Sometimes you may wish to leave some functions as they are, un-encrypted, but encrypt everything else.

To do this, give the function record an afAxonEncrypted marker tag and the function will be left alone.

The afAxonEncrypted marker tag is automatically added by Axon Encryptor to functions it encrypts. It does this so it knows not to encrypt the function twice!

By adding the afAxonEncrypted marker tag to function records yourself, it fools Axon Encryptor into thinking the function has already been encrypted, so it leaves the function alone and skips over it.

Notes on security

Axon Encryptor uses the Advanced Encryption Standard; which by encryption standards, is pretty strong.

Note that export laws in the United States prohibit Oracle from selling very strong encryption. This limits the encryption strength of the standard Java installation, and hence Axon Encryptor, to 128 bits. Stronger encryption is possible in Java but requires the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy to be installed.

Executing encrypted functions requires the use of a runtime key. While the software itself does not reveal the original Axon source code, anyone with the runtime key (including the end user) and extensive programming knowledge may be able to reveal the original Axon code.

For this reason, Axon Encryptor itself should be considered as an obfuscater only. The only way to truly keep your functions secure, is to not distribute them in the first place.

Licensing

Axon Encryptor is a Commercial product and requires a licence to be purchased (see below) to run unhindered.

One Axon Encryptor licence will enable unlimited encryption on a single instance of SkySpark. You will need to enter your SkySpark licence ID when purchasing, see Where is my SkyArc License ID? for details.

Purchased licences expire after 1 year. After this period all previously encrypted functions will continue to work as usual, but a new valid licence will be required to encrypt further functions.

Purchased licences should be downloaded to the /var/lic/ directory of your SkySpark installation.

Minor updates to Axon Encryptor may be provided free of charge, but major updates will require a new licence to be purchased.

Use of this software is bound the terms of the End User Licence Agreement (EULA) which can be found within the software download.

For support, please email -------------------------.

Evaluation mode

Although free to download, Axon Encryptor enters into an Evaluation Mode if it does not find a valid licence; whereby encrypted functions may only be invoked a maximum of 5 times and expire after 1 day.

To encrypt functions that will run unhindered, a valid licence may be purchased from StackHub.

Disclaimer

The software is provided "AS IS" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.