Locking options (full version only)

Top  Previous  Next

 

Note for evaluation version users: all the script locking options are disabled for the evaluation version of RubyEncoder. However, you may read below about the available options and script locking features that work in the full version of the encoder.

 

 

 --expire <dd/mm/yyyy>          

Using this option you can set an expiration date for the script. The script will NOT run on and after the specified date and comes with the error message: "script has expired".

 

 

 --expire <00d[00h[00m[00s]]]>                    

You can set the script to expire in a number of days/hours/minutes/seconds (from today). The script will not run after that time and will fail with the error message: "RubyEncoder Loader - the script has expired. Contact the script author about this problem. Error code [09]".

 

Example 1: --expire 10d

Example 2: --expire 1d12h

Example 3: --expire 90m

 --time-server <server, server, ...>

 

If you use the --expire option you may also wish to let the script get the world time from the online time service for checking time rather than using the server time. Use --time-server option to specify time servers. You may specify multiple servers IP addresses or domain names separated with "," or ";"

 

NTP protocol is used, UDP on port 123 on remote server. NTP is always tried at first. TIME protocol is the second, TCP on port 37 on remote server, checked if no response on NTP port.

 

If you specify a time-server option then your script will *require* the Internet connection in order to run. Time servers will be checked in the specified order. If neither of the servers from the list is available, the script will stop with the error:

"RubyEncoder Loader - the script requires an internet connection to run. The file has been encoded to run only when an internet connection is available. Setup an internet connection. Error code [20]"

 

It's a good idea to specify 2-3 time servers which will let your script work even if some of the time servers are temporary offline.

 

If you have multiple scripts included from each other and some of them were encoded with a time-server option then the script will access the time server only once for the first script for better performance and will use the time value from the time-server for the other included scripts.

 

A list of available time servers may be found here.

 

Locking the script to work only online

You may also use the time-server option to lock your script to run only online. Use the time-server option as usual for this but don't specify the expiration date for the script. The script will try to access the online time service and will fail if it's offline and hence not possible to read from the time server.

 

 --domain <domain>                

Bind the scripts to a domain name. The encoder will lock the script to run only from the specified domain and all sub domains. If an attempt is made to run the script from any other non-authorized domain, the script will fail with the error message: "RubyEncoder Loader - the script is not licensed to run on this machine or it is not running in a web server environment. Run this script in a web server environment. Contact the script author about this problem. Error code [02]". You may use this option more than once to specify multiple domains. This option may not be used with the --domain-encrypt option.

 

Domain name locking supports wildcards. You may lock to *.site.com and then the script will work for aa.site.com, bb.site.com etc. ? and * symbols are supported in the same manner as for specifying file masks.

 

Please note, the loader is able to check the domain name ONLY if the protected script is running in a web server environment. The web server must also provide the Ruby interpreter with one of the following environment variables; SERVER_NAME or  HTTP_HOST. The Apache web server does it by default for CGI interface. It also provides these environment variables for FastCGI but then it depends on the FastCGI server's resending these variables to the script. For the Nginx webserver you need to have an appropriate fastcgi_param line in the web server configuration file to have that variable passed to the Ruby script.For other web servers please find and use appropriate configuration directives.

 

As a developer you may wish to check if the SERVER_NAME or HTTP_HOST variable is available in the environment on the target server by investigating  ENV['SERVER_NAME'] or ENV['HTTP_HOST'] globals.

 

Hint: use the name of the main domain in this option, not the name of any sub domain unless you are sure you need to lock to a sub domain.

 

Example 1: --domain mydomain.com  

 

The script will run from mydomain.com, www.mydomain.com, myname.mydomain.com etc but will NOT run from otherdomain.com, www.otherdomain.com, otherdomain.net etc.

 

Example 2: --domain www.mydomain.com  

 

Script will run ONLY from www.mydomain.com. It will not run on the main domain mydomain.com and all other sub domains like myname.mydomain.com as well as other domains like otherdomain.com, www.otherdomain.com, otherdomain.net etc.

 

 

 --domain-encrypt <domain>      

Bind and encrypt the script with a domain name. The encoder will lock the script to run only from the specified domain. The encoder will also use a specified domain name as a part of the key for encryption for enhanced security. The loader will not be able to decrypt a script in it's run from the invalid domain and then the script fails with the error message: "RubyEncoder Loader - Loader - script checksum error. The encoded file has been modified. If the script requires a license file to run this error may be caused by an invalid license file. Install the original unmodified file or contact the script author about getting the original file or license file. Error code [12]". You may use this option ONLY ONCE in the command line. This option may not be used along with the other --domain options.

 

Be careful when using this option if you may possibly need to run your protected script from a sub domain. Example: --domain-encrypt mydomain.com will allow you to run the script ONLY from mydomain.com and not from www.mydomain.com and vice versa.

 

You should not use wildcards for domain name when using this option. This option works ONLY for one strictly specified domain name.

 

Please read the above comments about SERVER_NAME and HTTP_HOST environment variables. This is also related to --domain-encrypt option.

 

 --ip <x.x.x.x{/y.y.y.y}>        

Bind the scripts to IP/mask. The encoder will lock the script to run only from the specified IP address. The specified IP address mask will be applied to a real IP address before comparing to the target IP. So you may use this option to lock the script to multiple IP addresses if a mask is specified. If the script is run from any invalid IP address, the script will fail with the error message: "RubyEncoder Loader - the script is not licensed to run on this machine or it is not running in a web server environment. Run this script in web server environment. Contact the script author about this problem. Error code [01]" You may use this option more than once to specify multiple IP/mask pairs. IP address mask 255.255.255.255 is applied by default if not specified. This option may not be used with --ip-encrypt option.

 

Please note, the loader is able to check the domain name ONLY if the protected script is running in a web server environment. The web server must also provide the Ruby interpreter with one of the following environment variables; SERVER_ADDR or  LOCAL_ADDR. The Apache web server does it by default for CGI interface. It also provides these environment variables for FastCGI but then it depends on the FastCGI server's resending these variables to the script. For the Nginx webserver you need to have an appropriate fastcgi_param line in the web server configuration file to have that variable passed to the Ruby script.For other web servers please find and use appropriate configuration directives.

 

As a developer you may wish check if SERVER_ADDR or LOCAL_ADDR variable is available in the environment on the target server by investigating ENV['SERVER_ADDR'] or ENV['LOCAL_ADDR'] globals.

 

 --ip-encrypt <x.x.x.x{/y.y.y.y}>

Bind and encrypt to IP/mask. The encoder will lock the script to run only from the specified IP address. The encoder will also use the specified IP address with applied mask as a part of the key for encryption for enhanced security. The Loader will not be able to decrypt the script running from the invalid IP address and will fail with the error message: "RubyEncoder Loader - Loader - script checksum error. The encoded file has been modified. If the script requires a license file to run this error may be caused by an invalid license file. Install the original unmodified file or contact the script author regarding getting the original file or license file. Error code [12]". You may use this option ONLY ONCE in the command line. IP address mask 255.255.255.255 is used by default if not specified. This option may not be used along with other --ip options.

 

Please read the above comments about SERVER_ADDR and LOCAL_ADDR environment variables. This is also related to --ip-encrypt option.

 

 --mac <xx:xx:xx:xx:xx:xx>            

Bind the scripts to a LAN hardware (MAC) address. (Note, the "MAC address" name here is Media Access Control address and it is not related to Macintosh computers. All the computers connected to the Internet or LAN internally use MAC addresses). A MAC address is unique for the networking adapter and so it may be used for machine identification. A MAC address is 6 bytes long, with each byte represented in hex and separated with a ':' symbol.  The encoder will lock scripts to run only from the machine which has a networking adapter with the specified MAC address. If there is more than one network adapter installed then the script checks all of them. If the script is run from another machine, the script fails with the error message: "RubyEncoder Loader - the script is not licensed to run on this machine. Contact the script author regarding this problem. Error code  [03]" You may use this option more than once to specify multiple MAC addresses.

Hint: use 'ifconfig -all' command on MacOS, Linux or FreeBSD or 'ipconfig /all' on Windows to get a list of installed networking adapters and known MAC addresses. On Macs you may find LAN hardware addresses in System Preferences/Network/Advanced/Ethernet/Ethernet ID.

 

Alternatively you may use RGLoader::get_mac_addresses() API method and get an array filled in with MAC addresses detected on the machine where you run this method. It may be called directly or from the encoded Ruby code (not locked with any options). Note, as this API method is binary compiled into the loader, an appropriate RubyEncoder loader but me installed and loaded (require directive) before your code calls this method. We recommend that you create a mini project, encode it and include the loaders for obtaining MAC addresses from the client's machine, in that case loaders will be found automatically.

 

Locking the script to a LAN hardware address may be the only option to lock the script to a machine when the script is not running in a web server environment or some environment variables are not available for server IP address or server domain name check. E.g. running a script as cron task or a command line script.
 

 --machine-id <machine id>            

Bind the scripts to a machine ID. Machine ID is a unique identifier of the computer where your protected files are run. We use a special approach to know the machine ID and it differs for the platforms where RubyEncoder loader is installed. Machine ID is a hash represented as a hex code. The encoder will lock scripts to run only from the machine which has the same machine ID as specified in the option. If there are more than one --machine-id option used, then the protected code will run on any of them. If the script is run from another machine, the script fails with the error message: "RubyEncoder Loader - the script is not licensed to run on this machine. Contact the script author regarding this problem. Error code  [04]"

Use RGLoader::get_machine_id() API method and get the machine ID of the computer where you run this method. It may be called directly or from the encoded Ruby code (not locked with any options). Note, as this API method is binary compiled into the loader, an appropriate RubyEncoder loader but me installed and loaded (require directive) before your code calls this method. We recommend that you create a mini project, encode it and include the loaders for obtaining the machine ID from the client's machine before locking to it, in that case loaders will be found automatically.

 

Locking to a machine ID is an alternative to using MAC addresses locking for the scripts which are not running in a web server environment. E.g. running a script as cron task or a command line script.

 

 --machine-id-encrypt <machine id>

Bind and encrypt to a machine ID. The encoder will lock the script to run only on the machine with the specified machine ID. The encoder will also use the specified machine ID as a part of the key for encryption for enhanced security. The Loader will not be able to decrypt the script running from the invalid machine and will fail with the error message: "RubyEncoder Loader - Loader - script checksum error. The encoded file has been modified. If the script requires a license file to run this error may be caused by an invalid license file. Install the original unmodified file or contact the script author regarding getting the original file or license file. Error code [12]". You may use this option ONLY ONCE in the command line. This option may not be used along with other --machine-id options.

 

 --external <filename>          

 

Binds the scripts to an external license file. The scripts will require the license file in order to run. This file may be deployed along with the script or separately. This option lets you encode your scripts once and deploy to your clients with different licenses. Every license may have a different number of locks applied to it. You should specify only an external license file name here. Example: --external mylicense.lic  No real license file will be created during encoding. Use RubyEncoder licgen tool or GUI for creating a license file. When running protected scripts, and there is no specified license file found, the script fails with the error message: "RubyEncoder Loader - the script requires ... license file to run. Contact the script author regarding getting a license file. Error code [13]" You may use this option only ONCE in a command line. This option may not be used with any other locking options.

 

Since your code is bound to a license file, you may use locking options for the licenses rather than the encoded files. Therefore, the encoded files may remain the same for multiple clients while licenses (and locking options applied to them) differ per client.

 

 

The algorithm which is used for locking scripts to an external license gives your scripts much stronger protection from reverse engineering, unlocking and bytecode stealing, but it also gives you the most flexible way to generate trial versions of your products and to lock scripts to your customer's machine. This is the most powerful and flexible way to protect your scripts. We recommend that you use external license file locking for all your scripts. Using of locking to a license file is also the best way of deploying  the encoded project to different clients as you may encode once and then assign different restriction options for the clients in the licenses you generate per client.

 

Please read further details in the Using external script license generator section of the manual.

 

 --projid <value>

 

Specify a Project ID to identify your project. Project ID must be specified for the --external option. When you use the licgen tool for creating a license file, it is important to specify the same Project ID.

 

 --projkey <value>

 

Specify the Project Key to encrypt your project. Project Key must be specified for the --external option. When you use the licgen tool for creating a license file, it is important to specify the same Project Key.

 

The encryption algorithm uses the idea of two keys. The first key (Project Id) is stored within the encrypted area of protected scripts and used to decrypt an external license file. The second key (Project Key) is stored within the license file and used to decrypt the bytecode from the protected script.

This algorithm protects your product against creating a full working copy from the demo version by some people who may be interested in this. In order to decrypt and run the protected script a valid license file for the full version of your product is required. Otherwise it's impossible to decrypt and run the bytecode. Both Project Id and Project Key values are required if --external option is used.

 

 

 --remote-verification-url <URL>            

This option lets you use a special approach for protecting and locking your Ruby CLI scripts. Using of this option is preferred if your CLI script is a part of your encoded Ruby WEB project. In that case this option may be used for locking CLI scripts to run only on the same machine where your WEB part of the project is installed and run. A CLI script encoded with --remote-verification-URL will not run on another machine and will fail with the error message: "RubyEncoder Loader - the script is not licensed to run on this machine. Contact the script author regarding this problem. Error code  [05]"

 

For this option to work you need to do two things:
 
1) Create a special encoded ruby script which is accessible via HTTP protocol, it will be used to validate the machine and return the verification ID to the CLI script.The only directive you need to put into it is:

 
       print RGLoader::get_verification_id()

 
Note 1: if you use any frameworks, you may need to use another mechanism for sending a string to the output stream instead of print,
e.g. res.write for Cuba etc

 

Note 2: as get_verification_id() API method is binary compiled into the loader, make sure you have encoded the verification script.

 
Normally, you will add this to your WEB part of the project and encode it with RubyEncoder along with the other web Ruby files. You are free to use any name for this validation script. Example: verification_id.rb

 
2) When encoding your CLI script use --remote-verification-url option to specify the full URL to your web verification script and use the same project ID as for the web part of your code and particularly the verification script.

 

       Example: --remote-verification-url http://mydomain.com/verification_id.rb
 
Note 1: as the --remote-verification-url is mostly used only for locking of the encoded CLI scripts, consider separate encoding of the web part of your project and CLI scripts. You may create two GUI projects for that or use the command line encoder twice. Use the same Project ID/Project key for both!
 
Note 2: You may use standard locking to IP or domain for your web verification script (as usual for this to work your web server must send the information about current IP and domain to Ruby via environment). Anyway, you "lock" to the domain if use the domain name in the verification URL or lock to IP if you use IP in the URL - choose the way which suits your project and the deployment process.

 

Note 3: you should not worry about the delays HTTP adds, they are minimal as your CLI code and the main WEB code are both running on the same machine. However, it's recommended to check the verification URL is accessible from CLI, e.g. using 'curl' or 'wget'. If the domain name can't be recognised from CLI, you may add the domain name to hosts file or switch to using IP instead of the domain name.
 
However, if your CLI Ruby script works on its own and is not a part your your web based project, then you still may use locking to a machine ID described above as well as good old locking to MAC addresses.

 

 

Important Security Notice!

 

( ! ) Keep your Project Id and Project Key values in a secret.

 

( ! ) Remember your Project Id and Project Key. It's impossible to restore the values if forgotten. They are required for generating licenses for your customers.

 

( ! ) When generating the Project Id and Project Key manually, please use different values for Project Id and Project Key.