secureSWF User Manual

Version 4.5 - Build 3854

November, 2013

© 2013 Kindi LLC. All rights reserved.

Kindi LLC

Trademarks:

secureSWF, the Kindi logo, and the secureSWF logo are trademarks of Kindi LLC.

Flash, Flex, and ActionScript are trademarks of Adobe Systems Inc.

All other trademarks are property of their respective owners.

Warranties and Disclaimers :

THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

secureSWF is distributed under licenses restricting its use, copying, distribution, and decompilation.

Introduction - What's new

secureSWF v4.5 builds upon v4.0 100 new features delivering significant changes in AIR and APK support, new code protection techniques, major enhancements to Export to Ant utility, and a few GUI tweaks to make secureSWF even easier to use. The changes are:

  1. Eliminated the need for Flex or AIR SDKs. secureSWF can now sign AIR and APK files all by itself.
  2. Internal certificate for signing AIR and APK files when none is provided.
  3. Generate AIRI from AIR files and vice versa.
  4. Ability to protect native desktop AIR apps.
  5. Protection options have been enhanced to crash all the latest decompilers.
  6. Packages, classes, and non-private members are excluded from renaming in SWC files by default.
  7. Export to Ant now generates separate rules for protection options and renaming options.
  8. Fixed inconsistent results when protecting with GUI and then exporting to Ant.
  9. OS X 10.9 and Windows 8.1 support.
  10. Fixed retention of save each file as in Windows
  11. Fixed relative path issues on Mac
  12. Rules list in the configuration options tab got redesigned
  13. Added search for literal strings (cmd+f and control+f).
  14. GUI now saves maximized state.
  15. Fixed finding main SWF file in AIR and APK apps containing spaces in their names.
  16. Export to Ant utility now saves the latest used location.
  17. Fixed "Unable to parse the engine output" issue.
  18. Added ability to activate secureSWF from Ant.
  19. Fixed applying renaming values in configuration rules.
  20. Fixed all reported crashes which we were able to regenerate.

Installation

Before installing secureSWF, please make sure you have Java 6 or later.

For Windows, we provide an MSI installation file that will guide you through the installation process, which we trust you are familiar with. For Mac OS X, simply copy secureSWF.app into you Applications folder.

License Activation

secureSWF v4 requires an activation email and key. This information was probably emailed to you already. However, if you can't locate it, then contact our support team

If you don't provide the activation information, then secureSWF will run in demo version mode. The demo version will leave a visible watermark that says "Protected by secureSWF". You can use the demo version for evaluation purposes only. You are not allowed to publish protected Flash apps by the demo version.

When secureSWF activates, it generates a file named "key.data". It is a binary file which contains you license information as well as a list of MAC addresses of the network interfaces which were available at the time of activation. At least one of the registered network interfaces should be available each time you run secureSWF.

secureSWF will require the file key.data to be in the application folder. When you are running the GUI, the activation folder is:

  • Windows: %appdata%\Kindi\
  • Mac OS X: ~/Library/Application Support/Kindi/

When running secureSWF's CLI or Ant interfaces, you will manually set the application folder where secureSWF can find (or create) the file key.data.

Using secureSWF GUI

There are seven tabs in secureSWF. Each tab contains options which are related to each other. The following is a detailed explanation of each of the tabs:

Files Tab

Adding Files

Start by adding one or more SWF based files. secureSWF supports SWF, SWC, AIR (including .airi), and APK file formats. When you add multiple files, secureSWF will work with the files as a single project and will analyze them for shared classes. Therefore, you should not add multiple files to secureSWF unless they are part of the same application. If you want to batch process multiple files, then check how to do so using the command-line interface.

Once you add a SWF file, secureSWF will start by reading the identifiers and analyzing the code to determine the best protection configuration.

To protect native AIR desktop apps, please check Protecting AIR native installer files.

Presets

secureSWF is extraordinarily rich in features and is used for different purposes. Because of that, we have included five basic presets, preconfigured protection profiles, to help you get started quickly. Presets are intended to give you a quick start. After selecting your preferred preset, please explore the other options. The following table shows the five presets and the preconfigured value for each option:

Options \ Preset

Most Aggressive

Standard

Safe

Best Size

Testing

Rename Identifiers

true

true

true

true

false

Renaming Level

6

6

1

6

1

Post Build Check

true

true

true

true

true

Rename Local Variables

false

false

false

false

false

Renaming Mode

3

1

0

1

0

Use AS Keywords

false

false

false

false

false

Statement Level Randomization

3

0

0

0

0

Control Flow Percentage

100

20

0

0

0

Code Wrapping Level

3

2

2

1

0

Integer Data Obfuscation

true

false

false

false

false

Randomize

true

true

true

true

false

Literals Encryption Type

AES

RC4

RC4

RC4

RC4

Literals Encryption Level

9

1

1

1

1

Domain Lock Encryption Type

AES

RC4

RC4

RC4

RC4

Domain Lock Encryption Level

9

1

1

1

1

Prevent Local Playback

false

false

false

false

false

Remove Debug Data

true

true

true

true

false

Replace Debug Lines

false

false

false

false

false

Replace Debug Files

false

false

false

false

false

Merge Code Linkage

true

false

false

true

false

Merge Code Blocks

true

false

false

true

false

Remove Metadata

true

false

false

false

false

Sort Constants Pool

true

true

true

true

false

Finalize Classes

true

false

false

false

false

Finalize Methods

true

false

false

false

false

Staticize Methods

true

false

false

false

false

Privatize Fields

true

false

false

false

false

Privatize Methods

true

false

false

false

false

Remove Write-only Fields

true

true

false

false

false

Inline Constants

true

true

true

true

false

Read-only Fields to Constants

false

true

false

false

false

Remove Function Parameters

true

true

true

true

false

Remove Trace Calls

true

false

false

true

false

Remove Dead Code

true

true

true

true

false

Optimize Imports

true

true

true

true

false

Optimize Push Instructions

true

true

true

true

false

Optimize Integer Arithmetics

true

true

true

false

false

Super Compression

true

true

true

true

false

Optimize Images

true

true

true

true

false

Shape Optimization Intensity

2

0

0

2

0

Merge Lines Accuracy

1

0

0

2

0

Font Optimization Intensity

0

0

0

2

0

Image Re-compression Quality

7

0

0

6

0

Trim Tags

true

true

true

true

false

Trim Shapes Data

true

true

true

true

false

Trim Fonts Data

true

true

true

true

false

Remove Frame Labels

true

false

false

false

false

Remove Unused Fonts

true

true

true

true

false

Remove Unused Images

true

true

true

true

false

Remove Unused Shapes

true

true

true

true

false

Remove Unused Sounds

true

true

true

true

false

Remove Unused Sprites

true

true

true

true

false

Remove Unused Videos

true

true

true

true

false

Saving Files

Select a method for saving the new protected SWF files using the options in the Output Options group-box.

The following is a description of each option:

  • Save Output to Folder: The protected SWF files will be saved to the selected folder using the original filenames. If a file exists in that folder with the same name, it will be overwritten.
  • Add a prefix to filenames: The protected SWF files will be saved in the same folders the original files are in, but with adding the prefix text that you've entered (default "secure_" ) at the beginning to the filename.
  • Add a postfix to filenames: The protected SWF files will be saved in the same folders the original files are in, but with adding the postfix text that you've entered (default "_secure" ) to the end of the filename.
  • Save each file as: Gives you the ability to set a new filename for each file.

Make sure to avoid writing over the original files as secureSWF might attempt to read it again after it is done processing. secureSWF will not be able to read protected files.

Statistics

Brief information about the code of the added SWF files. It counts packages, classes, class members, and methods analyzed by secureSWF and ready to be obfuscated. The count does not include packages and classes of the SDKs and libraries secureSWF recognizes such as Flex or AIR.

Certificate Options

When using AIR or APK files, secureSWF will have to extract the SWF file out of the archive and make changes to it. Since AIR and APK files are signed archive files, secureSWF will have to re-sign them again using the certificate and password you used when compiling the files. These are the same signing options available in Flash Professional or Flash Builder.

If you don't provide a certificate for signing, secureSWF will use an internal certificate to generate the new AIR or APK file.

As of v4.5, secureSWF no longer has the need to call adt.jar (part of Adobe AIR tools) in the background to repackage and sign the file. Therefore, an AIR SDK is not required.

Protection Tab

Features in this tab are available for all secureSWF editions.

This tab includes options for transforming the compiled ActionScript bytecode to break decompilers. secureSWF uses four different methods to obfuscate the compiled instructions. This protection method is also referred to as ActionScript encryption or bytecode obfuscation.

General Code Protection Settings

1. Statement-level Randomization:

Restructures the bytecode which makes up an ActionScript line of code (statement). This makes the code almost impossible to decompile back into ActionScript. The performance and file size effects of this method depend on the source code. A block of code that has no branches will become smaller in size and will execute faster. On the other hand, extra bytecode instructions will be added to handle the branches which has negligible impact on the performance and file size.

You can set Statement-level Randomization to three levels; minimum, medium, and maximum. The degree of Statement-level Randomization will determine the size of the added code. Use maximum code wrapping for maximum protection, and minimum to get a smaller file.

2. Control Flow Obfuscation:

Adds random branches to the bytecode which will distract decompilers and disassemblers. This method increases the SWF file size depending on the selected intensity. You can set the intensity between 10% and 100%; a 10% intensity generates a smaller SWF file while a 100% intensity generates a more secure SWF file. Our testing results have shown that even a 10% intensity will prevent most decompilers from generating anything useful.

3. Dynamic Code Wrapping:

Wraps the ActionScript blocks with branches and junk bytes that effectively foils decompilers and disassemblers. The size and performance impact of this method is negligible. You can set Code Wrapping to three levels; minimum, medium, and maximum. The degree of code wrapping will determine the size of the added code. Use maximum code wrapping for maximum protection, and minimum to get a smaller file.

4. Integer Data Obfuscation:

Makes integer literals in your code harder to read.

You can use any of the four method either collectively or individually to prevent decompilers from viewing your ActionScript source code.

Randomization

By default, secureSWF will generate randomly obfuscated code every time you run it even if you are using the same configurations. Disabling this options will ensure obfuscated files will always be identical every time you run secureSWF using the same configurations. The result will still be randomly obfuscated code, but you will be able to regenerated it. You will find this useful for testing and verification. This applies to all secureSWF features including renaming and encryption.

You can optionally specify a seed value to control how to regenerate the random obfuscation.

Specific Code Protection Settings

Some parts of your code are certainly worth the overhead Control Flow Obfuscation adds and the file size increase Dynamic Code Wrapping does. However, you are probably happy leaving other parts of your code less protected for the sake of better performance or smaller file size.

TIP: you can filter packages in identifier browser tree on the left by pressing control+f or command+f.

This section enables you to override the general code protection settings. You can increase the intensity of protection for critical parts of you code and reduce (or entirely turn off) protection for trivial parts.

You can do that for an entire package, a specific class, or the exact method within the class. Selections override each other as follows: Package overrides general, class overrides package, method overrides class.

Setting an override for a package will apply to the classes and methods within the package. Same thing when setting an override for a class, it will apply to the enclosed class methods.

Renaming Tab

Features in this tab are available for secureSWF Standard and Professional editions. Renaming is not available in secureSWF Personal edition.

Options in this tab are regarding renaming ActionScript 3 identifiers. This includes packages, classes and class members. secureSWF will ignore SDK classes, which it can recognize, such as Flex and AIR SDKs, as well as helper classes. It will also ignore classes which names' begin with an underscore _ or a dollar sign $.

secureSWF v4 drops the ability to rename ActionScript 1 and 2 identifiers. For ActionScript 2 protection, please contact the [support team] (#http://support.kindi.com/) to give you access to secureSWF v3.

The checkbox Enable Identifiers Renaming has to be checked for any identifiers renaming to occur.

Renaming Options

Renaming Level

This will affect the amount of renamed identifiers depending on their likelihood of causing an issue if renamed.

When secureSWF analyzes your code, it reads all the identifiers it finds. It also ranks them by how "risky" could it be if the identifier got renamed. In other words, the likelihood that the code would break if secureSWF renamed that identifier.

secureSWF ranks and categorized identifiers into three renaming levels: Safe, Normal, and Risk. If you select any identifier from the browser below, you can see a Renaming Level value in the Identifier Settings panel on the right.

When choosing the Normal renaming level, all identifiers will be renamed except for the ones classified as Risky. The Safe renaming level will only rename identifiers classified as Safe. Finally, when choosing the Risky renaming level, all identifiers will be included for renaming ignoring the assigned renaming level category.

Reasons for classifying identifiers as risky vary and are subject to change. However, the following were found to be the most popular:

  • A class (or class member) ends with a numeric value.
  • Two classes in the same package (or members in the same class) end with different numeric values but have similar non-numeric part of the name. For example, Class1 and Class2.
  • Part of the identifier name exists as a literal string in the file. For example, trace("methodName") will cause methodName to be classified as a high risk identifier to be renamed.

Post Build Check will exclude any identifier with a similar name to any string left after renaming. This is done while protecting the files. To see a list of excluded identifiers, check the Summary tab.

What this option do is blindly look into the protected file strings and try to match any identifier name, ones set to be renamed only, with any string it can find. This process will greatly reduce the possibility of not fully renaming all the identifier's references and breaking the code. However, it also falsely warns about strings which are not identifier references.

If you have identifiers you want to rename but the Post Build Process is falsely excluding them, then you can set secureSWF to exclude these identifiers from the Post Build Process process using the Renaming Identifier Browser.

Rename Local Variables will rename the methods' local variables. It will only do so if the method itself is selected for renaming.

Local variables are usually removed by the compiler. However, in some cases, try-catch and nested functions, the compiler will keep the local variables names.

New Names Options

Generation Mode offers four ways for secureSWF to pick the new names for the identifiers being renamed. The Safe mode is preferred for Flex projects as the new names will remain compatible with XML. The Aggressive mode will use as many characters as possible to generate shorter names, which could include unprinted characters. The Binary mode will only use two characters for the new names. While the new names will be much longer, they will also be extremely hard to read for the human eye. The Long mode will use a long prefix and postfix for all generated names making it harder to distinguish from one another by the human eye.

Have fun trying them all out and picking which one is best for you.

New Name Prefix will add a prefix at the beginning of each new name regardless of the selected generation mode. This can be useful to avoid generating names similar to ones already existing in the application, or an already obfuscated part of the application.

Use ActionScript Keywords will randomly insert keywords as a new identifier name. When using this feature, about 50% of identifiers will consist of one or more space separated ActionScript keyword.

Mapping Table

The mapping table is a JSON file which contains the old (original) and new identifiers names. It is useful for translating error messages, which contains a call stack trace. Keep this file safe with your source code and do not publish it with your protected application.

secureSWF will always generate a mapping table when using the GUI. If you didn't specify a mapping table path, then secureSWF will use the first file output path and append _map to it.

Use this option to specify where to store the mapping table or where to load it from. If a mapping table already exists, then secureSWF will use it to lookup new names for renaming. It will also update the mapping table if there were new identifiers. Using this feature you can achieve incremental obfuscation.

Finally, mapping tables can be used to set the new names manually. Simply run secureSWF and let it generate a mapping table for you to start with. Then edit the generated mapping table in any text editor. The file is a straight forward JSON format which we are sure you will be able to figure it out by your own. Change the newName value to anything you want. When you run secureSWF again, the identifier will get renamed to the newName you had set.

Renaming Identifier Browser

This section is useful for specifying exactly which identifiers you want secureSWF to rename. It gives you full ability to override the default secureSWF configuration in two ways.

TIP: you can filter packages in identifier browser tree on the left by pressing control+f or command+f.

The first one is Rename. This option sets whether secureSWF should rename the identifier regardless of the selected Renaming Level. The second way is Post Build Check. If the identifier is set to be renamed, then you can also set whether it will accept any Post Build Check warnings. That is, if Post Build Check is disable for an identifier, then the Post Build Check process will not affect that particular identifier.

Whether you check or uncheck any of the options, you are setting a custom configuration for the identifier. Identifiers with bold fonts contain settings that will override global settings in the top section of this tab. To remove your custom identifier setting, you need to click the Clear button. Changing the settings back will still be interpreted as a custom setting.

For example, if you uncheck Rename for an identifier, it will mean that you do not what this identifier to be renamed. However, if you check it again, it will mean you want this identifier to be renamed regardless of the Renaming Level (override). To go be to the original status, you need to click the Clear button.

When the identifier is not in bold, you can use the Rename checkbox as an indicator of whether the identifier will be renamed based on the Renaming Level.

Encryption Tab

secureSWF encrypts string literals, domain locks, and the entire SWF file using industry standard symmetric RC4 and AES encryption algorithms.

Literal Strings Encryption

While obfuscation protects the code logic, valuable data such as access phrases and sensitive URLs remain in the SWF file as clear text. Attackers can simply open the SWF file using a text editor (after decompressing the SWF file) and view the literal strings in your code.

TIP: you can filter strings by pressing control+f or command+f.

Check next to any string in the table to encrypt it. You can use either RC4 or AES encryption algorithm. RC4 is light weight and fast, and AES provides the most secure encryption. Increasing the key length will increase security as well as the size and performance entailed overhead.

It is not recommended to select all literal strings when using AES encryption algorithm.

Clicking the Advanced button opens a dialog to check or uncheck multiple strings using a pattern. secureSWF will apply the action you click to the literal strings which match with the pattern.

The pattern can only begin or end with the '\*' wildcard character. To select all urls, enter 'http\*'. To select all xml file paths, enter '\*.xml'. To select all strings containing 'res' enter '\*res\*'. To select the string 'secret', enter 'secret'. The pattern is case insensitive.

Domain Locking

Inserting an encrypted domain lock to your SWF files will significantly decrease the chances of having your application launched offline or on other websites. The application will simply refuse to run if it is copied to a different location than what it has been locked to.

What makes this feature powerful enough to rely on is that the domains, which you have locked the application to, will be encrypted inside the SWF file and will only be decrypted at runtime. This makes finding out what is happening, and changing it, a very time and effort consuming task to a level that recreating the application from scratch is usually easier.

You need to include all the domains you want to allow your SWF files to run at. Use wildcard characters to cover all subdomain such as *.domain.com. Locking to domain.com will also include www.domain.com. To allow users to run the SWF files on their local machines, add "localhost" to the domains list.

You can use either RC4 or AES encryption algorithm. RC4 is light weight and fast, and AES provides the most secure encryption. Increasing the key length will increase security but at the cost of the file size.

Domain locking only works for ActionScript 3 based Flash applications for the Web.

Encrypted Loader

This features will fully encrypt your SWF file, create a loader SWF file using the selected template, and then place your encrypted file inside the loader to be decrypted securely at run-time.

This feature acts as a first line of defense. It protects all resources (images, graphics, sounds ... etc) from decompilers. If you have multiple SWF files, then a loader will be generated for each one of them.

Since your SWF file will be decrypted at runtime, your application cannot start until the file is entirely downloaded and fully decrypted. During that time, you can customize a preloader to be displayed to the users.

The preloaded consists of a background image, a progress bar, and an optional start and link buttons.

If you set a start button, then your application will not run until the user click start. The start button will become visible to the user after downloading and decrypting the original swf file is done. A link button, on the other hand, will open a url when clicked. The link button be visible within the preloader.

If you don't set a start button, your app will start automatically when loading and decryption is done. When you app starts, all the preloaded graphics will fade out and disappear.

Optimization Tab

Options in this tab enhances performance and reduces file size.

Code Optimization

Features are divided into three groups; bytecode structure optimization, class optimization, instructions optimization.

  • Remove debug data

Completely removes all information related to debugging if present.

  • Replace debug line numbers

If you want to keep useful call stack trace in error messages, you need to keep debug data present. However, if you don't need the line numbers, you can replace them with any integer to save file size.

  • Replace debug file names

It is highly recommended to replace debug file names with any random single character string. The file names are never needed when translating error messages with call stack trace.

  • Merge code linkage

Graphics and other resources are exported (linked) to ActionScript in different places in the SWF file. This option will merge export tags to save file size.

  • Merge code blocks

When bytecode is stored in multiple locations in the SWF file, merging the blocks together will save file size and enhance performance.

  • Sort constant pool

All constants in ActionScript are compiled into one table and then referenced by their index. Sorting the constant pool by putting the most accessed first will reduce file size.

  • Finalize classes

Will mark classes which are not extended by any subclass as final. This will allow the Flash player to better enhance code execution performance.

  • Finalize methods

Will mark methods which are not overridden by any subclass methods as final. This will allow the Flash player to better enhance code execution performance.

  • Staticize methods

Converts methods which do no access any class members to static. Calling static methods is faster than calling methods on objects.

  • Privatize fields

Sets class fields to private if not accessed outside the class. This makes accessing other public fields faster.

  • Privatize methods

Sets class methods to private if not accessed outside the class. This makes accessing other public methods faster.

  • Remove write-only fields

Class fields which are only written to and never read from can safely be deleted to enhance performance and reduce code size and enhance performance.

  • Constants to literal

Converts constant variable into literals when possible. This replaces the code which accesses the constant field by pushing its value as a literal into the operand stack. This highly increases performance.

  • Read-only fields to Constants

Class variable fields which are only read from will be converted to constant fields. This improves performance and works with the previous feature (*Constants to literal*) to further convert the constants to literals.

  • Remove function parameters

Function parameter names are sometimes kept in the compiled code. This option will completely remove them to save code size and enhance protection.

  • Remove trace calls

Using the method trace was useful while development. However, the Flex compiler keeps traces even after you export a release file. This option will remove the call to trace to improve performance, reduce the size, and further obfuscate the code.

Since the trace call parameters can be a function call or a property set, secureSWF will leave the parameter and only remove the call to the method trace.

  • Remove dead code

Removes code that is not reachable. Unreachable code can be generated by the compiler itself in many cases.

  • Optimize imports

Sorts imports to improve the class lookup speed.

  • Optimize push instructions

Will use the smallest required size for push instructions depending on its data. This will reduce the code size.

  • Optimize integer arithmetics

Replaces general arithmetic operation instructions with the appropriate instruction that is special for integers. This will improve code performance.

The effectiveness of the above options varies a lot depending on the nature of the application. While some of the options affect on performance is a slight enhancement, you will get a faster and smaller application when multiple options are applied together.

File Size Optimization

The following options will optimize the size of the SWF file. Most of the features are lossless. However, a few are lossy and will reduce the graphics quality.

  • Super Compression

Lossless (does not reduce quality) enhanced zip compression for SWF file. It takes longer time to compress the file but results in an average of 5% file reduction. Decompressing the file when it runs will not be affected at all.

  • Optimize Images

Uses the appropriate image encoding formats to reduce the file size without affecting the image quality.

  • Shape Optimization

A lossy (reduces quality) method to reduce the size of vector shapes. If the intensity is increased, the reduced graphics quality can be noticed.

It is recommended to use this option with low intensity where the degraded quality is very hard to notice.

  • Merge Lines

Uses fewer lines to draw the same shape. This will improve both rendering performance and reduce file size. It is also a lossy compression method that will degrade the graphics quality if the intensity is increased. With a low intensity, however, it will be very hard to notice the difference in graphics.

  • Font Optimization

Applies shape optimization to fonts data.

  • Image Re-compression Quality

Will re-compress JPG images using the assigned quality. This will highly reduce the SWF file size.

  • Trim Tags

Will remove unneeded data in any SWF tag to reduce file size.

  • Trim Shapes Data

Will remove unneeded data in shapes data bytes to reduce file size.

  • Trim Fonts Data

Will remove unneeded data in fonts data bytes to reduce file size.

  • Remove Frame Labels

Will remove frame labels and replace any access to them in ActionScript 3 by their indices.

  • Remove Unused Fonts

Completely removes fonts and all their data if were not used.

  • Remove Unused Images

Completely removes unused images.

  • Remove Unused Shapes

Completely removes unused shapes and their data.

  • Remove Unused Sounds

Completely removes unused sound data.

  • Remove Unused Sprites

Completely removes unused movie-clips or sprites.

  • Remove Unused Videos

Completely removes unused videos.

Exclude from Optimization

This panel is used to disable either the Class Optimization group or the Instructions Optimization group for any part of the application's code.

Clicking the Exclude button will open a dialog which is similar to Specific Code Protection Settings. You can exclude an entire package, a specific class, or the exact class member from either Class Optimization or Instruction Optimization. Selections override each other as follows: Package overrides general, class overrides package, class member overrides class.

Setting an override for a package will apply to the classes and methods within the package.

The options under Class Optimization group or the Instructions Optimization group need to be enabled for this feature to have any effect. This feature will not enable any option for a set of identifiers if that option was not enabled in the first place.

Method Inlining

Inlining short and static methods will greatly enhance performance. This feature will replace selected method calls by their entire code. The dialog for adding methods will only show methods secureSWF will be able to inline. For a method to appear in the dialing, it has to be declared static and relatively short.

It is recommended that you plan for which methods you want to inline while writing the code. Randomly inlining methods might cause issues and increase file size.

Configuration Tab

The configuration tab acts as a comprehensive control panel which will override any settings you have elsewhere. Using this tab, you can create any number of rules to override renaming, code transformation, and optimization settings for any package, class, or class member.

The ordering of the configuration rules is crucial. Rules down the list will override rules above them if their pattern property includes an overlapping set of identifiers.

Rule Editor

To create a rule, you need a pattern and to override at least one setting.

Tip: Right-click anywhere inside the Rule Editor to use a menu of common actions to save time

Rule Pattern

The pattern format consists of the following:

package::class/member

The "::" string separates the package name from the class name. The "/" character separates the class name from the class member name.

The class name and member name parts of the syntax are optional. You may use the wildcard "*" at the beginning or end of any section of the pattern. A pattern consisting of only a " *" will apply to all identifiers.

Examples:

com.kindi::Config_*

Will apply to all classes in the package "com.kindi" which begin with "Config_".

com.*

Will apply to all the packages witch names begin with "com.". It will also include all classes and class members in the packages.

com.kindi::SomeClass

Only applies to the class "SomeClass" which is in the package "com.kindi".

com.kindi::SomeClass/*

Applies to the class "SomeClass" and all its members.

Rule Overrides

You can override renaming, protection, or optimization settings. To set a rule to override a setting, you must first check the checkbox next to the option. This will apply the option value, which is in the popup menu under the checkbox, to identifiers matched by the pattern.

If you leave the checkbox unchecked, then this rule will not affect the setting for that option. For example, to disable renaming for all classes in the package "com.kindi", you need to enter the pattern "com.kindi::*" and check the "Rename" checkbox and make sure "Disable" is selected from the popup menu under the "Rename" checkbox.

There are eight types of overrides:

1. Rename: Overrides the Rename value of the identifiers.

2. Post Build Check: Overrides the Post Build Check value of the identifiers. When set to disable, matched identifiers will not be affected by Post Build Check process.

3. Statement-level Randomization: Overrides the Statement-level Randomization value of the matched identifiers.

4. Control Flow Obfuscation: Overrides the Control Flow Obfuscation value of the matched identifiers.

5. Dynamic Code Wrapping: Overrides the Dynamic Code Wrapping value of the matched identifiers.

6. Integer Data Obfuscation: Overrides the Integer Data Obfuscation value of the matched identifiers.

7. Class Optimization: Turns off all the Class Optimization options of the matched identifiers. This includes all the options listed under the Class Optimization section of the Code Optimization group-box inside the Optimization Tab.

Unlike other options, you can only disable Class Optimization options if they were turned on. You can also re-enable the options if they have been disabled by the previous rule. If all Class Optimization options were disabled in the Optimization Tab, then you cannot turn them on using configuration rules.

8. Instruction Optimization: Turns off all the Instruction Optimization options of the matched identifiers. This includes all the options listed under the Instruction Optimization section of the Code Optimization group-box inside the Optimization Tab.

Just like Class Optimization, you can only disable Instruction Optimization settings or re-enable them if disabled by a previous rule.

Configuration Rules

The Configuration Rules section of the this tab displays active rules. Double-click any rule to edit it. Right-click and you can select delete from a popup menu to delete a rule. Drag and drop to change the rules ordering.

Rule Ordering

The rules order will affect the result. Rules are applied one after the other. When rules' pattern overlap, then the first rule will be applied and changes will be made to the identifiers it affects. After that, the second rule in the list will also be applied and changes to the affected identifiers will be made again. Consider the following example:

Suppose you have a package "com.kindi", and inside it two classes, ClassA and ClassB. If you add the following rules:

1- Pattern: "com.kindi::*", Override: Rename=Disabled

2- Pattern: "com.kindi::ClassA", Override: Rename=Enabled

ClassA will get renamed, while classB will not get renamed. If you switch the order of the rules, both classes will not be renamed.

Tools

In secureSWF main menu, there are three items under the Tools menu:

Export to CLI

Exporting to CLI simply generates secureSWF.jar file in the selected folder. However, it is important to note that the generated Jar file corresponds to the activated edition of secureSWF. For example, if you are using the Demo version, and have not activated secureSWF, then the Jar file can only be used as a Demo. It cannot be activated later on.

In the same way, if you activated secureSWF using your Standard edition license key, the Jar file can only run as the Standard edition. When using the CLI Activate command, it will only accept a license key of secureSWF Standard edition.

Export to Ant

This tool will create a fully functional and ready to be used Ant script with the exact same settings as what is currently in the GUI.

Stack Trace Translator

When files are protected with identifiers renaming turned on, error messages with reference to the code will also be obfuscated. Because secureSWF generates a mapping table, you can still translate the code references in these messages.

In secureSWF GUI, go to Tools > Stack Trace Translator in the main menu. Select the mapping table file.

Paste the error message into the Original Call Stack Trace text area. The translated error message will automatically appear in the text area below it.

Protecting AIR Native Installer Files

To protect AIR apps which you want to deploy using the native installer (.exe or .dmg), you need to export your app either as an AIR package (signed .air file) or an intermediate .airi file. Whichever is easier for you. secureSWF will take in either formats.

In secureSWF, add the AIR file, then go to Certificate Options in the Files tab. In the Certificate Options dialog, make sure to select "Export as an intermediate AIRI that will be signed later".

After setting your protection configurations, click Protect and the output file will have .airi extension.

Have your p12 or pfx certificate file ready, the keystore and certificate passwords. You also need to have an AIR sdk installed.

Through the command line, you need to run the following:

     adt -package -storetype pkcs12 -keystore [Certificate Path] -target native [Output File] [Input .airi File]

Windows Example

[AIR SDK Path]\bin\adt.exe -package -storetype pkcs12 -keystore cert.p12 -target native out.exe secure_input.airi

Mac OS X Example

[AIR SDK Path]/bin/adt -package -storetype pkcs12 -keystore cert.p12 -target native out.dmg secure_input.airi

The Command-line Interface

secureSWF consists of a platform dependent native GUI and a cross-platform Java-based engine. The entire secureSWF engine is contained in a single jar file which you can copy to any platform.

To get started, open secureSWF GUI and go to Tools > Export to CLI. This will save the engine file, secureSWF.jar, to the selected folder. It will also save your license file, key.data, to the same folder.

NOTE: If you are using the demo version, then don't worry about key.data. However, you still need to set an execution folder when needed.

The license file has to exist in the execution folder (referred to as application folder in other places) when you run secureSWF from the CLI. Each machine you run secureSWF on has to have its own license file. You can use the license file which the GUI have generated if you intend to use secureSWF CLI on the same machine. If you want to use the CLI on a different machine, however, then you have to generate a new license file for that machine. You can do that by activating secureSWF on that machine via the CLI.

To run secureSWF CLI, you need to run it through Java (1.6 or later) using the following arguments:

java -Xmx1024m -jar secureSWF.jar (command) [-json]

The command can be one of the following:

  1. run
  2. analyze
  3. execute
  4. translate
  5. activate

The -json argument is applicable for analyze, execute, and activate where it will force the CLI output to be in JSON format, even error messages. You can use this to programmatically parse the output of secureSWF.

secureSWF CLI Commands

run

Syntax:

java -Xmx1024m -jar secureSWF.jar run (SecureSWFPath) (InputFile)
[(preset|domain|encrypt|inline|out):value]    
[--overrides [attribute:value]]   

SecureSWFPath is the execution folder in which the file key.data can be found. secureSWF will also need to use this folder to extract the super compression utility binary file.

InputFile can either be a SWF based file (swf, swc, air, or app) or can be a project (ssp4) file.

Other arguments are optional. There are two groups of optional arguments. The first group is [(preset|domain|encrypt|inline|out):value] part of the syntax. Some of these arguments can be used multiple times if needed. The second group is the [--overrides [attribute:value]] part of the syntax and is called the overrides group. This is because arguments in this group work to change, and override, the values set by the first group (i.e. presets or project files).

The first group consists of five types of arguments:

  • preset sets a pre-configured setting profile. It is useful when the InputFile is a SWF file. If the InputFile is a project file, then the preset will also be applied and will change the project file settings.

Examples: preset:testing, preset:standard, preset:bestSize, preset:mostAggressive, preset:safe.

If you don't set a preset and the InputFile is a SWF file, then the normal preset is used.

  • out is for setting an output path to save the InputFile to. It can be used as out:path. If the InputFile is a project file, then it will apply only to the first file in the project. If you have multiple files, then use the outputValue and outputMethod attributes in the overrides group (the second group).
  • domain is for adding a domain name to the domain locking list. This attribute can be used multiple times to add multiple domain names. Example: domain:kindi.com
  • encrypt is for adding a string to literal strings encryption. Examples: encrypt:"http://someurl/" encrypt:passphrase encrypt:"some string with spaces"
  • inline is for adding a method name to the method inlining list. The method name needs to be the full qualifies name. Example: inline:com.kindi.AClass.SomeMethod

The overrides group of arguments, the second group, consists of 67 attributes which covers every feature in secureSWF. The same list of attributes is shared with Ant. Therefore, to avoid rewriting the long list, please check the section on attributes here.

To use the attributes with the CLI run command, you need to first put the --overrides switch and then list as many attributes as you need after the switch in the syntax attributeName:value

Examples:

java -Xmx1024m -jar secureSWF.jar run secureSWF4 file.swf 

Will protect file.swf and save it as secure_file.swf using the standard preset.

java -Xmx1024m -jar secureSWF.jar run secureSWF4 file.swf   
out:protected.swf preset:safe encrypt:"http://url/"    
domain:kindi.com --overrides controlFlow:100    
removeTraceCalls:true mergeLines:5

Will protect file.swf and save it as protected.swf using the safe preset. It will also encrypt the string "http://url/" and lock the file to kindi.com. secureSWF will also set control flow obfuscation on using 100% intensity, remove trace calls, and enable Merge lines with 50% intensity.

java -Xmx1024m -jar secureSWF.jar run secureSWF4 project.ssp4   
--override codeWrapping:3 removeDebugInfo:True

Will protect the content of a project file using the settings stored in the project file. However, it will override Dynamic Code Wrapping and set it to maximum and will remove debugging data.

analyze

While the run command almost does everything you may need, the CLI also provides analyze and execute pair of commands which are used by secureSWF GUI.

The analyze command prepares a project file for the execute command. It will read and analyze the SWF files, generate the list of identifiers with the renaming levels, and generate a list of literal strings which can be encrypted.

It will basically generate a project file JSON content. The project file can be edited (either manually or programmatically) and then passed to the execute command.

Syntax:

java -Xmx1024m -jar secureSWF.jar analyze <input file(s)>    
[-preset <presetName>] [-out <outputFile>]

  • Input files can be a single swf file, a list of swf files, a project file, or a project file followed by a list of swf files.
  • -preset switch sets which preset to use as the basis for analysis. The default is the normal preset. Accepted values are: "mostAggressive", "standard", "bestSize", "safe", and "testing".
  • -out has to be the last argument and sets an output file to write the project files JSON content to. If you don't supply one, secureSWF will print the content to standard output.

Examples:

java -Xmx1024m -jar secureSWF.jar analyze file1.swf

Will create new project settings for file1.swf and print its content on standard output.

java -Xmx1024m -jar secureSWF.jar analyze file1.swf -preset   
safe -out myProject.ssp4

Will create new project settings for file1.swf and save its content to myProject.ssp4. The project will be created with the safe preset.

java -Xmx1024m -jar secureSWF.jar analyze myProject.ssp4 -out
myProject.ssp4

Will update myProject.ssp4 incase the code was changed.

java -Xmx1024m -jar secureSWF.jar analyze myProject.ssp4   
file2.swf -out myProject.ssp4

Will update myProject.ssp4 and add file2.swf with identifiers analyzed.

execute

This command will process a project file generated by the analyze command and protect the files in it. The syntax is as follows:

java -Xmx1024m -jar secureSWF.jar execute projectFile secureSWFPath

All arguments are required. projectFile has to be a valid ssp4 file. The license file, key.data, needs to exist in secureSWFPath.

translate

A command line interface for translating error messaging containing call stack trace. This is similar to the Stack Trace Translator tool from secureSWF GUI.

Syntax:

java -jar secureSWF.jar translate logFile mappingTableFile

logFile is a text file containing the error message you need to translate.

mappingTableFile is the JSON file which contains the mapping table. It should have been generated by secureSWF when you protected the application.

activate

Activate will register your secureSWF license information with the activation server and generate a license file, key.data, for the machine which you are running this command on.

NOTE: Each edition of secureSWF has a different Jar file. When you exported the Jar file from the GUI, it generated a Jar file for the edition which was activated. If you have not activated secureSWF GUI, then the Jar file is for the Demo version and cannot be activated.

The syntax is:

java -jar secureSWF.jar activate regEmail regCode secureSWFFolder

regEmail is your registration email

regCode is your registration code

secureSWFFolder is the secureSWF folder which you are going to use in the commands run and execute. The file key.data will be saved to that folder.

Ant Script Integration

The fastest way to get started is by using the Export to Ant tool in secureSWF GUI. It will prepare a complete folder containing the build.xml and all required files. You can then make changes in the GUI and see how that reflects in Ant.

Defining secureSWF Protect Task

You need access to secureSWF.jar engine file first. After that, you can define the task as follows:

<taskdef  resource="secureSWF/ui/ant/resources/task.properties" classpath="secureSWF.jar"/>

This will add the protect task to your build script.

Protect

Protect is the only task secureSWF defines. It has the following attributes:

  • applicationPath: The secureSWF path which contains key.data
  • regEmail: Your registration email. It is only required if secureSWF is not activated yet.
  • regCode: Your registration code. It is only required if secureSWF is not activated yet.
  • logFile: You can set a log file for secureSWF to write its output on. If you don't set one, then secureSWF will write the output on the standard output steam.

In addition to the above, the protect task also takes all the 67 attributes of secureSWF which can be found here.

Encrypted Loader Graphics Attributes

The Protect task also supports the following attributes for altering the loader graphics:

  • loaderBackgroundImage: JPG image file to be used as a background.
  • loaderLinkImage: PNG image file to be used as the link button image.
  • loaderLinkImageOver: PNG image file to be used as the link button image when the mouse hovers over it.
  • loaderLinkUrl: Sets the url for the link button.
  • loaderLinkLeft: The distance between the beginning of the link button and the left side of the loader in pixels.
  • loaderLinkTop: The distance between the beginning of the link button and the top side of the loader in pixels.
  • loaderStartImage: PNG image file to be used as the start button.
  • loaderStartImageOver: PNG image file to be used as the start button image when the mouse hovers over it.
  • loaderStartLeft: The distance between the beginning of the start button and the left side of the loader in pixels.
  • loaderStartTop: The distance between the beginning of the start button and the top side of the loader in pixels.
  • loaderProgressbarWidth: Width in pixels for the progress bar.
  • loaderProgressbarHeight: Height in pixels for the progress bar.
  • loaderProgressbarLeft: The distance between the beginning of the progress bar and the left side of the loader in pixels.
  • loaderProgressbarTop: The distance between the beginning of the progress bar and the top side of the loader in pixels.
  • loaderProgressbarBorderColor: The color of the progress bar borders in hex format.
  • loaderProgressbarFillColor: The color of the progressing part of the progress bar in hex format.
  • loaderProgressbarBackgroundColor: The background color of the progress bar in hex format.

Nested Elements

Inside the Protect task, you can use the following elements:

InputFile

For adding a SWF-based file to be protected. It has the following attributes:

  • filePath: is the file path for the SWF-based file you want to protect.
  • outputPath: is an optional attribute to set the output location and name for this file. The outputMethod Protect fast attribute needs to be set to "map" in order for this attribute to take its effect.

For multiple files, use this element multiple times. For example, to protect two files together use:

<protect>   
        <inputFile filePath="file1.swf">
        <inputFile filePath="file2.swf">
</protect>

Rule

The rule element is used to set specific configuration for certain group of identifiers. It is similar to the GUI Configurations Rules.

The Rule element accepts the following attributes:

  • filter: (required) a pattern used to match with identifiers that will be affected by this rule. The filter accepts the following syntax:
package::class/member

Example:

com.kindi::Config_*

Will apply to all classes in the package "com.kindi" which begin with "Config_".

com.*

Will apply to all the packages witch names begin with "com.". It will also include all classes and class members in them.

com.kindi::SomeClass

Only applies to the class "SomeClass" which is in the package "com.kindi".

com.kindi::SomeClass/*

Applies to the class "SomeClass" and all its members.

  • ns: sets in which namespace should the matched identifiers be. Default value is any namespace.
  • rename: Enables or disables renaming for the matched identifiers.
  • slr: Overrides statement level randomization value for the matched identifiers.
  • controlFlow: Overrides Control Flow Obfuscation setting for the matched identifiers.
  • codeWrapping: Overrides Dynamic Code Wrapping value for the matched identifiers.
  • integerObfuscation: Overrides Integer Data Obfuscation setting for the matched identifiers.
  • postBuildCheck: sets whether or not should the matched identifiers be affected by the Post Build Check.
  • optimizeClass: sets whether the matched identifiers should be included in optimization options which will affect the class structure.
  • optimizeInstructions: sets whether the matched identifiers should be included in optimization options which will affect the code instructions structure.

Multiple rules can be used. When matched identifiers by rules overlap, the last rule will override previous rules.

When you don't set an attribute, it does not mean it will have a default value. An unset attribute means that the rule will not override values for this attribute.

DomainLock

You can add multiple domain locks using this element when used inside the Protect task. The DomainLock element has a single value attribute. Therefore, to add domain locks, simply do:

<DomainLock value="*.kindi.com">
<DomainLock value="files.secureswf.com">

InlineMethod

The InlineMethod element can be used to inline methods as follows:

<inlineMethod methodName="com.package.SomeClass.theMethod">

The attribute methodName expects the qualified name of a method which exists in the application and is static.

LiteralString

The LiteralString element is used to encrypt string literals in the application's swf files. It has the following attributes:

  • value: The string you need to encrypt
  • match: could either be "exact" or "contains". If set to contains, then strings containing the any string containing the value will be encrypted.

Examples:

<literalString value="http" match="contains">

Will encrypt all urls and any other string which contains "http".

secureSWF Attributes for CLI and Ant

The following attributes can be used in the CLI run command or in the Ant protect task. The same attributes can also be found in secureSWF ssp4 project files with the same names and value range.

Troubleshooting

We have a detailed troubleshooting guide in a separate document here.