Protecting Linux Applications

Using Sentinel LDK Envelope

To protect a Linux application:

1. Define and store protection parameters in a Sentinel LDK Envelope configuration file.

Sentinel LDK Envelope configuration parameters are described in Configuration File Structure.

By default, Envelope looks for a configuration file called envconfig.cfgx in the same directory as the Envelope executable.

You also have the option of specifying any or all of the protection parameters in the command line that you use to run Envelope.

• If you specify a given parameter both in the configuration file and in the command line, Envelope uses the value that you specify in the command line.

•If no value is specified for a given parameter in either location, Envelope uses the default value (if any) for that parameter.

2.Ensure that binary stripping is not performed. (Binary stripping is not supported for protected applications.)

For example: For an application that will be installed using an RPM package, add the following line at the beginning of the RPM .spec file:

%global __os_install_post%{nil}

This is required so that the package archive will include the protected application.

3.Run the Sentinel LDK Envelope for Linux executable.

NOTE   

Envelope can be used on a 64-bit Intel platform to protect 32-bit (only ARM) and 64-bit (Intel and ARM) executables and shared objects.

For Linux applications that were protected using Envelope: The installer for the protected application should determine if libXaw libraries are present on the end user's computer and, if not, install them.

Use one of the following formats to run the Envelope executable:

./linuxenv -h (or --help)

Displays the Envelope parameters.

./linuxenv [-c:<configFile>] (or --cfg:<configFile>)

Runs Envelope with the specified configuration file. If no configuration file is specified, Envelope uses the default configuration file described in step 1 (if the default configuration file exists).

./linuxenv [-c:<configFile>] [<protectionParams>] [<inputFile> <outputFile>]

Runs Envelope with the specified configuration file. If no configuration file is specified, Envelope uses the default configuration file described in step 1 (if the default configuration file exists).

Envelope uses any protection parameters specified in the command line instead of parameters specified in the configuration file. The available protection parameters are described in the table that follows.

If input and output files are specified in the command line, Envelope uses them to determine the application to protect instead of files specified in the configuration file.

Envelope supports protection of the following file types:

– Linux executables

– Linux shared objects (*.so)

Protection Parameters for Sentinel LDK Envelope Command Line

The table that follows describes parameters that can be optionally included in the Envelope command line. If a parameter exists both in the command line and in the configuration file, Envelope uses the parameter in the command line.

NOTE    For a more complete description of each parameter, see the parameter descriptions in Configuration File Structure.

Parameter Description  
-v:<filename>

--vcf:<filename>

File that contains the Vendor Code used by the protected application to access the required Sentinel protection key.

  
-f:<id>

--fid:<id>

Feature ID. If no Feature ID is specified here or in the configuration file, the default Feature ID (0) is used

.		  
-b:<time>

--bgchk:<time>

Enables background checks. Time is in seconds. (0 = disabled)

For more information, see the description of <BACKGROUND_CHECK>.

  
-i:<repeats>
--ignore: <repeats>

Number of grace periods (if any) to grant the user if a background check determines that the required protection key is not connected.

For more information, see the description of <IGNORE_BACKGROUND_CHECK>.

  
--randomize:<val>

Whether section information should be randomized.

>0 = Disabled. The symbol table is removed. Thales recommends this option.

>1 = Partial. The symbol table is retained; only strings are randomized.

>2 = Full. The symbol table is also randomized.

  
-d

--debug

Allow debugging for the protected application.

This parameter is applicable for both executables and shared objects.

  
--memdump

By default, memory dumps are disabled, and no core is generated in case the protected application fails. If this parameter is present, memory dumps can be generated for the protected application.

This parameter is applicable for both executables and shared objects.

NOTE   When debugging is allowed, memory dumps are also allowed regardless of the setting for the memdump parameter. (Protection against memory dumps does not work when debugging of the protected application is allowed.)

You can use either of two methods to take a memory dump:

1.kill signal - When using this method, specify --memdump to enable memory dumps for the protected application.

2. gcore (or other memory dump tools) - When using this method, you must specify both --memdump and --debug. Tools like gcore attempt to attach to the process as debuggers, so debugger detection must be disabled.

 

  
-e:<level>

--enclevel:<level>

Encryption level (1–5). As you increase the encryption level, the security of the protected application increases. However, the start-up time also increases.

  
--external-runtime: <module>

The Envelope runtime module path for an external uClibc module. Sentinel LDK Envelope for Linux supports certain uClibc modules. This support can be provided on demand. Contact Technical Support for the list of supported external modules and for package delivery.

Note: This can only be specified in the command line. No equivalent parameters exist in the configuration file.

  
--exclude-section: <sections>

The encryption of certain ELF binary sections may impact the runtime performance (in terms of vmRSS) on devices where swap area is not supported.

You can use this parameter to disable the encryption of a section. Use multiple parameters to disable the encryption of multiple sections. For example:
--exclude-section:abc --exclude-section:xyz

  
-c:<file>

--cfg:<file>

Sentinel Envelope configuration file for Linux. By default, Envelope looks for a file called envconfig.cfgx in the same directory as the Envelope executable.

  
-m:<file>
--msg:<file>

File that contains the definitions for messages displayed by the Run-time Environment to end users at run-time. By default, Envelope uses a file called messages.msgx.

Note: This can only be specified in the command line. No equivalent parameters exist in the configuration file.

  
--keep-symbol-table

Preserves a shared object's symbol section in the protected shared object to enable linking against it at build time.

Note: This option adds additional imports from pthread and dl shared objects into a protected shared object. Thus, it is required to resolve pthread and dl dependencies at build time.

The following example compiles the main application with a protected shared library:

g++ -o main main.cpp -L<libraryPath> -l <protectedSharedObject> -lpthread -ldl
  
--pip-opt-out:<val>

Envelope collects data on the ways that Sentinel LDK Envelope is used by vendors to protect their software applications. This data enables Thales to better understand which features are most important to you and where to allocate resources to improve the Sentinel LDK product. The data accumulated is stripped of identifying elements before transmission to Thales. For information on the data accumulated, see Product Improvement Program: Data Transferred.

You have to option to discontinue your participation in this program.

The possible values for this parameter are:

>0 = Envelope collects and transmits data to Thales. Thales recommends this option.

>1 = Envelope does not collect and transmit data to Thales.

Default: 0

 
--msg-out:<val>

The message output mode at run-time.

>0 = no message output

>1 = GUI

>4 = console

>5 = GUI and console

  
--dfp

Insert the Data Protection module into the protected application. This enables the protected application to access data files that were protected with the Sentinel LDK Data Protection utility. For more information, see the description of protecting data files in the Sentinel LDK Software Protection and Licensing Guide (for Sentinel EMS or Sentinel LDK-EMS).

  
--wchar

Writes run-time errors as wide character strings. Required when you specify that messages will be output to a console (values 4 or 5 in the previous switch).

  
-q

--quiet

Only error and warning messages are displayed.

Note: This can only be specified in the command line. No equivalent parameters exist in the configuration file.