5.4. Keys
The following shows the Keys tab of the Project Settings dialog:
Dynamic and external keys provide a way of adding extra security to the encoded files. Dynamic keys are expressions that have to be evaluated at runtime before a function or method can be decoded successfully. External keys are files or string values that are separate from the encoded file and which have to exist for the file to be decoded and run successfully. We recommend that you read the External and Dynamic Keys chapter of the User Guide PDF for full details on how they work. We will cover the basic points of the features below.
Dynamic decoding means that functions and methods are only decoded when they are first called in the application, rather than when the encoded file is read. This means that the decoded byte code is only obtained at the last possible moment. Dynamic keys enhance dynamic decoding by requiring an expression to be evaluated before a function is decoded. The result of the expression will be used to decrypt the byte code of the function in the ionCube Loader. Dynamic keys are specified as comments in the original source code of your application and the expression may be a URL, a variable or function. In the comment there should also be the expected value of the expression and that value will be used by the Encoder to encrypt the byte code of the function.
External keys are files or string values that are separate from the encoded file. Those values are essential to decode the file successfully. The location of the keys may be set within the encoded file, within a PHP configuration file (php.ini file) or within a license file.
Settings for Dynamic Keys
Dynamic and external keys are set within the Keys tab of the current project settings, as shown in the image above. The top part of the Keys section is for the dynamic keys and the lower part is for the external keys. The section for the Dynamic keys consists of the following:
- A panel describing how the dynamic keys should be set within your PHP source code.
- Functions to which the reflection API in PHP may be applied. Some reflection functions need the function to which they are being
applied to be decoded before they will work. However, that may mean that the function would be decoded before it is first called.
The default, None, is for no functions to be decoded for the reflection API. You can also allow All functions to
be decoded for the reflection API and you can also supply a file that lists patterns for which functions and methods may have the reflection API
applied to them. Those patterns will have one of the following four forms:
- myfn where myfn is the name of an ordinary function (not a method) in your code.
- MyClass::foo where foo is the name of a method in class MyClass.
- MyClass::* which means all methods in class MyClass.
- Lang\Translate\* which means all functions and methods in the Lang\Translate namespace.
Detection of Dynamic Keys when encoding
If a dynamic key is detected when encoding that will be output in the Event Log as can be seen in the image above where the function called protected_fn has a dynamic key.
Settings for External Keys
The External key settings section is in the bottom part of the Keys tab. That section consists of the following:
- A check box that, if ticked, means that an external key will be used.
- Settings for the location of the external key.
In the settings for the external key, you will need to give the value to be used when encoding and also the location of the external key at runtime. There are three possibilities for the location of the key at runtime:
- A file path is located in the encoded file. The contents of the file at that path will be used as the key by the Loader. You will also need to choose the local path for the key when encoding.
- A php.ini property that will give either a string or a file path of an external key at runtime. The full name of the property in the ini file will be ioncube.loader.key.propname where propname will be the name that you choose for the property. If you want the value of the ini property to be a string then you will need to provide that string in the options. If you want the value of the ini property to be a file path then you will need to provide a local file for the key when encoding.
- A license property can be the key. As the with ini properties, the value can be either a string or a file path. You will need to ensure that the license is generated with a property that has the same value used when encoding.
Here are some examples of how the external keys may be set as php.ini and license file properties:-
The image above shows the setting for an external key that will be a php.ini property and where the value is a string. In this case the full name of the ini property at runtime should be ioncube.loader.key.keyprop.
The image above shows the setting for an external key that will be a php.ini property and where the value is a full file path. In this case the full name of the ini property at runtime should be ioncube.loader.key.extkey. The file found from the ini property must have the same contents as the file used when encoding.
The image above shows the setting for an external key that will be a license property and where the value is a file. The license must be generated with the same property name, keylicprop, and have a value that is a full path to a file with the same contents as the local file used when encoding.