User`s guide

150 Creating FPM Application Licenses
the C macro DONT_TRANSLATE_NAMES before each of these files. The names of the routines
to be used all begin with “LICMGR_”
If you use the supplied implementation of the HMAC-MD5 digest algorithm, you can optionally
turn it into a non-standard algorithm by adjusting the pre-defined HMAC_IPAD_XOR_VALUE and
HMAC_OPAD_XOR_VALUE values. If you want to modify the pad XOR values, you must define
them as one-byte hex values. Creating a non-standard algorithm may be useful if you want to
further protect your FPM application in the event the secret key defined for your FPM is
compromised. However, this theoretically may reduce the strength of the digest.
Echelon makes no recommendation regarding the use of this feature.
4. Returns the license key to the i.LON License Generator, which converts the license key to ASCII
text and then generates the .XML file to be supplied to your customers. You must set the
expression *ppLicenseKey to point to the memory area containing the binary license key (the
“digest”) generated by your security algorithm, and you must set the expression
*pLicenseKeyLen to the byte length of the binary license key.
Using the Sample Security DLL File
If you do not have the resources to build the security DLL file, you can use the sample pre-built
security DLL file provided with the i.LON SmartServer 2.0 Programming Tools (demo or full
version). This executable file, LicenseSecurityHMACMD5.dll, is located in the
LonWorks\iLON\Development\Licensing\iLONLicenseGen folder.
To use this file, you just rename it to “LicenseSecurity.dll”. This file implements a standard HMAC-
MD5 digest algorithm from “open source” code. The source code for this sample DLL is in the file
LicenseSecurityHMACMD5.cpp, located in the
LonWorks\iLON\Development\Licensing\iLONLicenseGen folder. Note that this sample security
algorithm is not guaranteed to be suitable for any particular scenario.
The user is solely responsible for selecting a security algorithm in the security DLL file and in
the FPM application. Echelon makes no recommendations regarding the suitability of any
security algorithm.
Enabling License Validation in an FPM Application
You need to modify your FPM application so that it can check whether a customer’s SmartServer has a
valid license for running your FPM. This entails writing a separate license validation routine in the
source file of your FPM (.cpp extension). Your license validation routine must perform two major
tasks: (1) verify that the Lock ID (MACID, LUID, or other user-defined lock type) specified in the
FPM license file matches the one on the customer’s SmartServer, and (2) verify that the license key in
the FPM license file is valid. The FPM license is the .xml file you created with the i.LON License
Generator as described in Creating FPM Licenses in this chapter. This file must be installed in (or
under) the root/config/license folder on the SmartServer flash disk.
To verify the lock ID, your license validation routine must call the built-in license manager on the
SmartServer and provide it the license ID (Company Name and Feature Name) specified in the FPM
license file, and the file path of the FPM license relative to the root/config/license folder on the
SmartServer flash disk. The license manager will then check that the Lock ID in the FPM license
matches the one on the SmartServer (this is referred to as the Node Lock Check). The license manager
then returns the result of the Node Lock Check and the data in the FPM license file to your license
validation routine. The license data is returned as a structure that contains the license type, lock type,
lock ID, options, license key, and the length of the license key.