Locking options

Top  Previous  Next

Locking

 

This window is used for setting locking options for encoded scripts. All the locking options are stored internally encoded within your protected script. You may choose "Lock to external license file" option to put all locking settings into a special encoded file which acts as a license file for running your protected scripts. You need to specify a license file name in order to use this option.

 

 

Set expiration date

 

Choose a date you wish your script to expire. The script will not run on and after the specified date and display the following error message: "Protected script has expired".

 

 

Script will expire in (days)

 

Select after how many days the script will expire starting from today. The script will not run on and after the specified date and display the following error message: "Protected script has expired".

 

 

Online time servers for date check

 

If you use an expiration date lock option for your scripts you may wish to let them check time with online time services rather than use local server time which may be potentially changed. You may specify a list of time servers. Old TIME and modern NTP protocols are supported. The list of time servers is automatically filled in for a new project using the default settings from Preferences.

 

Please note, using this option will require the Internet access on the machine where your protected scripts run. Time servers are checked according to the list and if the first server is not replying then the second one is tried and so on. Using this option adds a delay to running your protected files because of accessing online time services via the Internet. If you use this option we suggest that you specify at least two time servers or more for reliability. If none of the specified time servers can be reached when your protected Ruby code is running, it will fail with an error.

 

Time servers will be checked for protected scripts only if "Check date with online time servers" option is also selected.

 

Find further information about time locking, time servers and using the appropriate command line option here.

 

 

Run from these IP addresses only

 

Lock scripts to IP/mask. The encoder will lock the script to run only from the specified IP address(es). A specified IP address mask is applied to the real IP address before comparing. So you may use this option to lock the script to a subnet if a correct mask is specified. If a protected script is running from the IP address which is not allowed, the script terminates with the error message: "This script is not licensed to run on this machine". You may add as many IP address/mask pairs as you need. Click '+' button if you need to add another IP/Mask pair. Click '-' button if you want to delete the selected IP/Mask.

 

IP address mask 255.255.255.255 is used by default if not specified.

 

Please note, the loader will be able to check the domain name for a protected script ONLY in a web server environment. The web server should provide the Ruby interpreter with one of the following environment variables SERVER_ADDR or  LOCAL_ADDR. Apache web server does it by default for the CGI interface. It also provides these environment variables for the FastCGI interface, but it depends on the FastCGI server to provide 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 look at the configuration accordingly.  

 

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

 

Locking to IP addresses works only for scripts which will run on web servers. As there is no a definite IP address when the script runs from the shell (command line) you should NOT use locking to IP address for scripts which are intended to be run from shell e.g. for cron jobs.

 

 

Encrypt with IP

 

Lock and encrypt scripts to IP/mask. You may specify only one IP/mask. The encoder will lock the script to run only from the specified IP address. The encoder uses a specified IP address with an applied mask as a part of the key for encryption for providing maximum protection. RubyEncoder Loader will not be able to even decrypt the script that runs from the wrong IP address and display an error message: "Protected script checksum error". IP address mask 255.255.255.255 is used by default if not specified.

 

Locking to IP addresses works only for scripts which will run on web servers. As there is no a definite IP address when the script runs from the shell (command line) you should NOT use locking to IP address for scripts which are intended to run from shell e.g. for cron jobs.

 

Find further information about IP locking and using the appropriate command line option here.

 

 

Run from these domains only

 

Lock scripts to a domain name. The encoder will lock the scripts to run only from the specified domain and all the sub domains. If an attempt is made to run the script on a non-authorised domain, the following error message is displayed: "This script is not licensed to run on this machine". You may add as many domain names as you need.

 

Please note, the loader will be able to check the domain name the protected script is running under ONLY in a web server environment. The web server should 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 a CGI interface. It also provides these environment variables for the FastCGI interface but it depends on the FastCGI server to provide 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 look at the configuration accordingly.  

 

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 printing ENV['SERVER_NAME'] or ENV['HTTP_HOST'] values.

 

Use the name of the main domain in this option, not the name of any subdomain until you are sure you need to lock to a subdomain.

 

Example 1: 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: www.mydomain.com  

 

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

 

You may use * and ? wildcards when specifying a domain name. Wildcards have their usual behavior similar to a file system.

 

Example 3: *.mydomain.com  

 

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

 

Example 4: *mydomain.com (please note a change from the previous example)  

 

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

 

Locking to domain names works only for scripts which will run on web servers. As there is no a definite domain name when the script runs from the shell (command line) you should NOT use locking to domain name for scripts which are intended to run from shell e.g. for cron jobs.

 

 

Encrypt with domain

 

Lock and encrypt scripts to one domain. You may specify only one domain. The encoder will lock the script to run only from the specified domain name. The encoder will use a specified domain name as a part of the key for encryption for providing maximum protection. The Loader will not be able to even decrypt the script that runs in the wrong domain name and will display an error message: "Protected script checksum error". You should not use wildcards for domain name when using this option. This option works ONLY for one strictly specified domain name.

 

Locking to domain names works only for scripts which will run on web servers. As there is no a definite domain name when the script runs from the shell (command line) you should NOT use locking to domain name for scripts which are intended to run from shell e.g. for cron jobs.

 

Find further information about domain locking and using the appropriate command line option here.

 

 

Run from these MAC addresses only

 

Lock the script to LAN hardware (MAC) addresses (The "MAC" word used here has nothing about Apple Macintosh computers. MAC address is a hardware address of the local area networking LAN controller available for all platforms). This address is usually unique for every networking adapter and so it may be easily used to identify a machine. A MAC address is 6 bytes long, with each byte represented in hex and separated with a colon (:).The encoder will lock a script to run only from the machine which has a networking adapter with a specified MAC address. If there is more than one LAN adapter installed then script will check all of them. If an attempt is made to run the script on a machine that is missed a correct adapter, then the script fails with the error message: "This script is not licensed to run on this machine". You may specify multiple MAC addresses, if any one address matches then the script runs.

You may use 'ifconfig -all' command in Linux or OSX or 'ipconfig /all' in Windows to get a list of installed networking adapters and know MAC addresses.

 

Find further information about MAC address locking and using the appropriate command line option here.

 

       

Run from these machines only

 

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. 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 specified, then the protected code will run on any of these machines. If the script is run from another machine, the script fails with the error message: "This script is not licensed to run on this machine."

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.

 

 

Encrypt to 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: "Script checksum error." This option works ONLY for one machine ID.

 

Find further information about machine ID locking and using the appropriate command line option here.

 

 

Remote verification      

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: "Tthe script is not licensed to run on this machine"

 

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, specify the full URL to your web verification script in this option and make sure you are encoding both your CLI script and the verification script as parts of the same GUI project, or, if you prefer to use separate encoding projects, use the same project ID and Key for the web part of your code and the verification script.

 

       Example: http://mydomain.com/verification_id.rb
 
Note 1: 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 2: 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.

 

Find further information about remote verification and using the appropriate command line option here.

 

 

Script will only work online

 

If you do not use a time locking option you are still able to lock your scripts to work only online. Select this option if you need your protected scripts to work only online (when the Internet connection is available). RubyEncoder Loader will check if the script it is running online by trying to access one of the time servers specified in the list. The list should not be empty! As mentioned above, this may add delays to executing of your protected files

 

 

Custom defined constants

 

RubyEncoder lets you define custom named constants during encoding process or within an external license file. Constant name/value pairs are stored internally in the encrypted area of the protected script or the external license file. They may be used for custom script locking, adding copyrights or any other actions if you need to store a custom value in protected scripts or your script license file and then retrieve it from your protected Ruby code.

 

You may define multiple name/value pairs for your custom constants.

 

To get a predefined constant value from the encoded script use RGLoader::get_const() RubyEncoder API function. This function is defined in the RubyEncoder loader and returns a predefined RubyEncoder constant value or nil if constant with the specified name is not defined. RubyEncoder constants names are case sensitive.

 

Syntax: string RGLoader::get_const( string )

 

Additionally there are 5 constants predefined for all protected scripts:

 

RGLoader::get_const("encoder")

Returns the name of the encoder - "RubyEncoder"

RGLoader::get_const("loader_version")

Returns an internal version of the loader

RGLoader::get_const("encode_date")

Returns UNIX timestamp for the date when the script was encoded

RGLoader::get_const("license_date")

Returns UNIX timestamp for the date when the script license was created. It's may differ from the  "encode_date" when an external script license is used

RGLoader::get_const("expire_date")

Returns script expiration date as UNIX timestamp if it's defined in the script license or internally with in the script during encoding

 

Find further information about custom defined constants and using the appropriate command line option here.

 

 

Custom error handlers

 

You may add custom error handling functions which will catch script licensing errors. An error handler should be a function which accepts two parameters:

 

error_handler( code , message )

 

You may use any name for this function. Also you may have different functions for different script errors. The first argument will contain an error code. The second one will contain a default error message. To set a custom error handler use --catch option for the command line rubyencoder command or set your error handler on the Locking screen.

 

There are following error handler conditions defined:

 

Err tag

Returned

Code

Default message

Restricted to run

01,02,03,

04,05

This script is not licensed to run on this machine.

(code indicates a reason: 01-IP, 02-domain, 03-MAC address,

04-machine ID, 05-remote verification URL locking)

License broken

06

A license file which is required to run this protected script is invalid...

License expired

09

This script has expired...

License not found

13

This protected script requires ... license file in order to run

Running offline

20

This protected script requires the Internet connection in order to run

All errors

-

-

 

"All errors" is a special value to specify one error handler function for all RubyEncoder error codes.

 

The custom error handler function should be defined before an error may occur. The best place for it is "custom header" code as it's loaded before any license checking is done and so the error handler will be always available if defined there. But you may also define a custom error handler function in another encoded file which is run before the script that may cause a license error. Don't put any passwords or secret data if you use a "custom header" code for defining an error handler as this code is stored unencoded.

 

Find further information about custom error handling and using the appropriate command line option here.

 

 

 

External license file name

 

If you use the "Lock to external license file" option then you need to specify a license file name. Scripts encoded with this option will require a license file in order to run. If the name of the license file does not include any path then protected scripts will search for the license file in the protected script's folder, then its parent folder and so on. So you may have one license file for the entire project if the license file is located in the project's root. Alternatively, an absolute full path may be specified for the license. If the protected script cannot find the specified license file, it fails with the error message: "script requires ... file to run".

 

The license file may be generated later using GUI or the command line license generator "licgen".

 

Locking your scripts to an external license file gives additional protection to your scripts. Using locking to a license file is the best if you need to deploy one script or the entire project to different users, but need to use different restriction options for each of them. Find more about how it works here.

 

Find further information about custom error handling and using the appropriate command line option here.

 

 

Generating a license file

 

To generate a license file click on "Generate License" button. Please refer to Generating a license file section for further details.