 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
secureSWF Manual
Getting StartedWhile secureSWF provides a wide array of protection for Flash applications, getting started with a level of security that could well be all you need is a simple 3-step operation. Secure your SWFs - Easy as 1-2-3!
Of course you will want to explore the many protection options available in secureSWF to get the maximum benefits for your situation. The rest of this guide will introduce you to the major areas of the product to explore next. At the conclusion of this guide you should be well on your way to understanding how to use secureSWF to achieve the security and performance levels that are right for your Flash applications. Back to the topGetting Started with secureSWF Protection SettingsWhile you can get a pretty good level of protection for your SWF files using presets, these are only the tip of the iceberg when it comes to your options for securing your Flash apps. It will of course take some time to master everything secureSWF has to offer, but it shouldn't take you too long to get acquainted with the major product features and settings and arrive to the level of protection that's good for your needs. Let's look briefly at the main things you should look at when devising a security scheme for your applications. Identifiers Renaming Tab
Main Options:
Exploring Packages and Classes The Identifiers Renaming tab displays a tree of the packages and classes in your application, and it shows which classes will have identifiers renamed with the standard renaming defaults. When you select any class on the left, its members are displayed on the right. 
Basically what you want to do here is look through the classes, see which ones will have identifiers renamed by the default renaming (these are checked in the listing), and decide whether you want to have more classes processed, and set options for renaming. You can as get granular as you want by selecting individual classes for renaming and making settings for each selected class. Back to the topProtection Options TabThis tab provides the second major security features area of secureSWF. It provides options for code transformations, file optimization, domain locking, and encryption of embedded string literals. Code Transformation Encrypted Domain Locking 
Optimization Literal Strings Encryption 
Rules Tab
TroubleshootingAfter protecting your SWF files, we highly recommend to test them. If the protected files are not functioning properly, then one or more of secureSWF protection options requires further tuning. Please follow these simple steps to find out what went wrong.
Identifiers Renaming TroubleshootingWhile secureSWF tries to automatically deselect identifiers that cause problems when renamed, some identifiers will still slip away and require you to manually deselect them. First of all, please set identifiers renaming Level to Safe and make sure that Automatically handle warnings and Generate mapping table are checked. Process the files, if the protect files are still not working properly then please follow the following steps:
Code Transformation TroubleshootingNote: This section is for ActionScript 3 only. With secureSWF v3.4, you can now disable code transformation options for one or more function (getters, setters, and class constructors as well) while leaving it enabled for the rest of the code. If there is a problem with Control Flow Obfuscation or Dynamic Code Wrapping, the Flash Player (debugger version) will throw one of the following errors:
After the error message, you will find a call stack trace. If the identifiers in the call stack trace are renamed, you can either use the Stack Trace Deobfuscator tool in secureSWF, or disable Identifiers Renaming. Note: If Control Flow Obfuscation is set under 100% intensity, the error might not occur all the time. This is because this algorithm will choose random places to alter the control flow if set under 100% intensity. For testing, we recommend setting Control Flow Obfuscation to 100%. If you are getting one of the errors in the pervious table after obfuscating your files with secureSWF, look up the last function name, class, and package in the call stack trace. This is usually the function that is causing the error when obfuscated. You need to disable code transformation for this method only.
To do that, click on the Advanced button in the Code Transformation group-box. This will open a dialog where you can disable Control Flow Obfuscation, Statement-level Randomization, and Dynamic Code Wrapping for the function that is causing the error when obfuscated. Choose the file that has the error (if you have multiple files), then choose the package, and the class that contain the function. The table at the bottom of the dialog contains all the functions, getters, setters, and the class constructor of the selected class. You should be able to find the function name that appeared in the call stack trace in that table. Click on the cells next to the name and disable all the option. Close the dialog and click on Process again. This should fix the error. Back to the topDetailed Documentation of secureSWF OptionsThe following is a detailed documentation of secureSWF features and options to help you better understand how to use each section and how it will affect your code. Project FilessecureSWF is designed to handle either a single SWF file or multiple SWF files that interact together. The Project Files section allows you to add the SWF file(s) that you wish to protect. To get started, click on the "Add" button and select the SWF file(s) that you wish to protect. Or, alternatively, drag the SWF file from your file browser into secureSWF. 
Once you've added the SWF file(s), you will notice that secureSWF starts analyzing the code and automatically determining the best obfuscation settings. You will also notice that there are a number of statistics about the SWF file(s) that you've added in the bottom-right group-box. Now, you can directly click on the "Protect SWF Files" button on the upper-right corner to protect and save the SWF files. Or, optionally, select one of the Protection Presets that suites you. Saving The FilesYou should select the method of saving the new protected SWF file(s) using the options in the Output Options group-box. The following is a description of each option:
Protection PresetsYou can avoid digging deeper into the settings by selecting one of the Protection Presets. You can set secureSWF to generate the most aggressively protected SWF files or to generate a smaller SWF file size. The following is a detailed explanation of each preset:
Most Aggressive: Standard (default): Safe: Best Size: Testing: Identifiers RenamingOne of the most powerful features of secureSWF is its ability to rename just about every identifier in your SWF file from variables and functions names to frame labels and symbol names in addition to AS3 and AS2 classes. Not only that, but also secureSWF automatically determines the identifiers that are safe to rename and the identifiers that are not. secureSWF has the ability to rename the following identifiers:
To enable Identifiers Renaming make sure that the Rename Identifiers checkbox is checked. There are 6 tab pages (2 for AS3) in the Identifiers Renaming section:
Renaming LevelsecureSWF will help you determine which identifiers are safe to rename. You can change the renaming level from normal to either rename everything or to only rename identifiers which are never referenced by a literal string in anyway. Aggressive RenamingAggressive Renaming turns your identifiers into string tokens that misleads decompilers, foils code formatters, and most importantly greatly distracts the code reader. When this feature is turned on, new identifiers names can be just numbers, operators like +, /, *, ?, ! and so on, whitespaces such as a space, tab, and many other unprinted ASCII characters. Aggressive renaming will choose a digit or one of the 51 symbols (such as &, $, #, backspace, enter .. etc) for the first character of the identifier's name. This will ensure that the new identifiers names are all illegal names for ActionScript. If you have less than 61 identifier in your SWF file, then all the new names will be a single character that is either a number or a symbol. With v3.3 you now have control over Aggressive Renaming. In previous versions, it was always turned on. Aggressive Renaming will be turned on by default for AS2 projects and off for AS3 projects. When disabling Aggressive Renaming, all the new identifiers names are going to be numbers preceded by '_-' (without the quotes). This makes the new names illegal for ActionScript but fine with XML. You will find turning Aggressive Renaming off useful when using XML data-binding with Flex. Back to the topUse ActionScript KeywordsWhen this feature is turned on, Identifiers Renaming will use ActionScript reserved words (keywords), such as switch, case, if, while, do... etc, for 38 of the new identifiers names. It will randomly select the identifiers that will be renamed to ActionScript keywords. This option, is turned on by default for both AS2 and AS3 projects. Additional RenamingOptions in Additional Renaming renames or removes identifiers that do not appear in the identifiers tree and tables:
PostBuild WarningsWhen you process the SWF files (by clicking on the "Protect SWF Files" button), secureSWF will check if there are still strings in the SWF files that match any of the identifiers. If a string matches an identifier, a warning dialog will appear. It is recommended to click "Deselect and Reprocess" in this case. secureSWF will automatically handle this for you when "Automatically handle warnings" is checked.
Randomly restructures the bytecode instructions that makes up an ActionScript statement making it almost impossible decompile the source code. The performance and file size effects of this method depend on the source code. A block of code that has no branches (for example, if-statements, for loops, or function definitions) 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 increase in the SWF file size. Control Flow ObfuscationAdds extra branches to the bytecode that distracts 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 protected SWF file. Our testing results have shown that even a 10% intensity will break all known decompilers most of the time. Dynamic Code WrappingWraps the ActionScript blocks with branches and junk bytes that effectively foil 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. Break Function CallsMakes it much harder for a decompiler to find out what parameters are being passed to a function call. Back to the topAdvanced Code TransformationNote: This feature is only available for ActionScript 3 With secureSWF v3.3, we added a new dialog that you can use to set Statements Level Randomization, Control Flow Obfuscation, and Dynamic Code Wrapping on the method body level.
Is all code created equal? We do not think so. Some parts of your code are definitely worth the overhead Control Flow Obfuscation adds and the file size increase Dynamic Code Wrapping does. But you are probably happy leaving other parts of your code less protected for the sake of better performance or smaller file size. Now with this new feature, which opens up by clicking the "Advanced" button in Protection Options tab, you can override the code transformation settings for each function. But the most useful thing about this is overriding the settings for code that breaks after obfuscation. For example, if you get an unbalanced stack verification error after obfuscating a file, you no longer have to turn off Control Flow Obfuscation for the entire code. You can now turn it off for the function that is causing the error which is usually at the top of the call stack trace. Check out the Code Transformation Troubleshooting section. Back to the topOptimizationBy renaming identifiers to smaller names (to one or two characters), removing frame labels and metadata, and applying code optimizing techniques, secureSWF can actually be used as a SWF optimization tool to generate files that are smaller in size and lighter to play. secureSWF also has the following optimization techniques:
Super CompressionThis feature will reduce the SWF file size by an average of 10% by running an advanced compression algorithm that requires more time for compression but will not affect the decompression speed or the application performance at all. 
This compression algorithm favors file size over compression speed by performing an exhaustive search of all patterns and is equipped with an advanced block splitting technique. The default setting will reduce the file size as close to smallest possible size as pre-compression calculations can predict but you probably can still shove some more bytes by trying out different Huffman blocks values. This is not the actual block count, but every value will generate a different file size. From our experience, the difference between the default setting and the best Huffman blocks value is less than 100 bytes only. And there is no way you can tell which value will be best, you just have to try. Back to the topLiteral String EncryptionWhile obfuscation protects the code logic, valuable data such as access passwords and sensitive URLs remain in the SWF file as clear text. Malicious users can simply open the SWF file using a text editor (decompress the SWF file if compressed) and view the literal strings that exist in your code. secureSWF allows you to select the literal strings in your SWF file, encrypt them in the SWF file using a very secure symmetric encryption algorithm, and decrypt them only when needed at runtime. Please note that this entails an added overhead each time the string is accessed. To use this features, look up the strings in the table. It shows all the literal strings, the number of occurrences, and their location. Simply, check the strings that you wish to encrypt. Back to the topEncrypted Domain LockingInserting an encrypted domain lock to your SWF file(s) will greatly decrease the chances of having your application launched offline or on other websites. The application will simply refuse to run if it was copied to a different location than what it has been locked to. What makes this feature powerful enough to rely on is that the locations (URLs or domains) you have locked the application to are encrypted inside the SWF files 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. Domain locking works differently for AS2 and AS3. For ActionScript 2, use the URL or the beginning of it to lock the application. For example, to allow the application to work on website.com, you will have to enter "http://www.website.com/" and "http://website.com/". You may also want to include "https://" as well. This will allow users to run the application as long as the URL it is being launched from begins with "http://www.website.com/" or "http://website.com/". You can also go deeper and specify a folder. For example, you can enter "http://www.website.com/folder/" and "http://website.com/folder". Now, the SWF files has to be in the folder "folder" or its sub-folders on website.com. Finally, to allow users to run your application locally, add "file://" to the domains list. For ActionScript 3, you should use the domain name, not the URL. For example, enter "website.com" and "www.website.com" to allow users to run the application while it is hosted at website.com. You cannot specify a folder or a sub-folder for AS3. To allow users to run the SWF files on their local machines, add "localhost" to the domains list for ActionScript 3. Make sure to add all the domains and their variations that you want to allow users to launch your application from. Back to the topRulesTo help you even control how secureSWF processing your code more easily, we added a global rules panel to secureSWF v3.4. Using this panel, you can create any set of rules to override renaming and code transformation settings for every package, class, or even class member. This is done by first specifying a pattern to match targets with. For example, 'com.kindisoft.util.*' will match all classes and class members in the package 'com.kindisoft.util'. And 'com.kindisoft.util.Md5' will include the class Md5 and all it's members. After that, just override the options you would like this rule to apply. You can enable/disable identifiers renaming, and Statement-level Randomization, or set a specific value for Control Flow Obfuscation or Dynamic Code Wrapping. For options that you don't override, secureSWF will either apply the default setting, or the value that you have set in other places.
Back to the top Encrypted Loader CreatorThis tool will help you to highly decrease the chances of having your SWF files downloaded or used offline. It simply creates a new SWF file which dynamically loads your original SWF file into it. To increase this feature's power and reliability, the name and location of the original SWF file are encrypted. In addition to that, you can change the extension of the original SWF file into any random string (i.e. .mp3 or .js). This will make finding the original SWF file in the browser cache a much harder task. The main important gain from using this tool is that users who will try to use SWF rippers (grabbers) will not be able to download the original SWF file at all. Using the Encrypted Loader Creator Tool
Stack Trace DeobfuscatorThis tool will help you translate error message from AS3 based obfuscated SWF files when running them in the stand-alone Flash Player. You will find this tool very handy in troubleshooting. There is an XML mapping file generated for every protected file when the option Generate mapping table is enabled. The mapping file name follows the pattern protectedFileName_map.xml and is saved in the same path as the protected file. To use this tool, click on browse and select the mapping table for the file that generated the error. And then paste the error message from the Flash Player in the text area and click Trace. This will deobfuscate the error message showing the identifiers in their original names.
Command-line InterfacessecureSWF has a command-line interface that could be used for batch execution and build process integration. Using the CLI is different on each platform: WindowsYou can use the command-line interface in two forms:
ssCLI.exe Project_file Output_folder [override_options]
Or
ssCLI.exe SWF_file Output_folder [options]
OS XYou can use the command-line interface in two forms:
ssCLI Project_file Output_folder [override_options]
Or
ssCLI SWF_file Output_folder [options]
LinuxYou can use the command-line interface in two forms:
secureSWF Project_file Output_folder [override_options]
Or
secureSWF SWF_file Output_folder [options]
The options will override the project settings and secureSWF's defaults as the following:
Switches are used in the following format: -[switch]:[value] For example:
ssCLI.exe myProject.sspj c:\output -slr:off -controlFlow:50 -wrap:3
Or using the short form for the switches
ssCLI.exe myProject.sspj c:\output\ -s:off -c:50 -w:3
This will load the SWF files and settings for the project file, turn off Statement-level Randomization, setControl Flow Obfuscation to 50%, set Dynamic Code Wrapping to maximum, and save the protected files in the folder c:\output. Back to the topAnt Script IntegrationDescription You can integrate secureSWF obfuscation process into your Ant script by first defining an Ant task as the following:
<taskdef name="protect" classpath="secureSWF.jar" classname="secureSWF.ant.ProtectTask"/> Note: Please make sure to have secureSWF.jar your classpath. After that you can use the new Protect task with attributes and nested elements as shown below. There are two ways to use secureSWF through Ant. The first one is by using the projectFile attribute, which will load all the settings from a project file that you can export from the GUI first then override them using other attributes and nested elements. The other way is to specify all the settings you want in the Ant script and specify a Fileset nested element to load the SWF files. Attributes
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Nested Elements
FileSet
As with regular Ant FileSet element, you can add a number of files to be protected. Example:
<fileset dir="/home/test/Sample4" includes="**.swf" />
This will be ignored if a project file was specified in the Protect task.
Rule
Using a rule element, you can force secureSWF to rename or leave unrenamed any type of identifier such as packages, classes, frame labels ...etc. You can also specify code transformation options for any function. You can add multiple renaming or code transformation rules to your ant task.
Attributes
Attributes have no default values, they will override any other settings you have specified.
| Attribute | Description | Type |
|---|---|---|
| filter | Pattern match identifiers or functions with. | String |
| statementLevelRandomization | Override Statement-level randomization. | Boolean |
| controlFlowObfuscation | Override Control Flow Obfuscation. 0 means off, 1 to 100 is the intensity. | Integer |
| dynamicCodeWrapping | Override Dynamic Code Wrapping. 0 for Off, 1 for Minimum, 2 for Medium, or 3 for Maximum. | Integer |
| select | When set to true, will force secureSWF to rename the identifiers that this rule applies to. And will leave identifiers unrenamed if set to false. | Boolean |
| publicOnly | Apply the rule to public class members only | Boolean |
Example:
<protect outputPath="/home/test/sample/secure">
<fileset dir="/home/test/sample" includes="**.swf" />
<rule filter="com.data.helpers.*" select="false" />
<rule filter="com.kindisoft.Util.md5" statementLevelRandomization ="true" controlFlowObfuscation="100" />
</protect>
Back to the top LiteralString
You can specify strings that you would like to be encrypted in the protected files by using LiteralString nested elements.
The following will encrypt the string "Pas$W0rd" if found in any of the SWF files.
<literalString value="Pas$W0rd" />
domainName Encrypted Domain Locks
Adding a domain to the list of encrypted domain locks is much like adding a literal string.
<domainName value="kindisoft.com" />
Sample Build.xml file
<project name="test" default="protect" basedir=".">
<taskdef name="protect" classpath="secureSWF.jar"
classname="secureSWF.ant.ProtectTask"/>
<target name="protect">
<protect keyFilePath="/home/test/secureSWF/key.data" outputPath="/home/test /sample/secure">
<fileset dir="/home/test/sample" includes="**.swf"/>
<rule filter="com.data.**" select="false"/>
<literalString value="sEc.R3t"/>
<domainName value="kindisoft.com"/>
<domainName value="www.kindisoft.com"/>
</protect>
</target>
</project>
Back to the top