Some time back, we posted a simple technique for hiding assets and AS3 code from prying eyes by embedding one SWF within another SWF. In this post, we revisit that topic and look at how ROT128 can be used to provide an additional layer of protection.

Step I: Apply ROT128 To Actual SWF
Using the following code, we will apply ROT128 to the SWF that is going to be embedded:

// assuming the raw data of the SWF has been stored in a variable swfBytes
var j:int = swfBytes.length;
while (j--)
{
	swfBytes[j] += 128;
}

The following shows a simple tool you can create to load a SWF file, apply ROT128 to it, and save the encrypted file.

• Flash Player 10 is required.
• Click the Browse button to bring up a native file dialog.
• Select a Flash Movie (.swf) file.
• Click the Save button that will be shown after loading the SWF file.

(80×80 SWF, 2KB)

You can verify that encryption has been done by running the saved SWF file “ActualSWF.swf” – it should show a blank screen.

Remember, applying ROT128 twice restores the file, so the tool can also be used to restore a previously ROT128-encrypted file if the algorithm used was the same (same n increment, same conditional loop).

The ROT128SWF class:
(please feel free to customize to fit your own requirements)

package 
{
	import flash.display.Sprite;
	import flash.display.Stage;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.events.Event;
	import flash.events.MouseEvent;
	import flash.events.IOErrorEvent;
	import flash.net.FileFilter;
	import flash.net.FileReference;
	import flash.text.TextField;
	import flash.text.TextFieldAutoSize;
	import flash.text.TextFieldType;
	import flash.text.TextFormat;
 
	public class ROT128SWF extends Sprite 
	{
 
		// ** minimalist text button **
		private var opButton:TextField;
 
		// ** browse/load/save **
		private var swfFile:FileReference;
 
		public function ROT128SWF():void 
		{
			if (stage) init();
			else addEventListener(Event.ADDED_TO_STAGE, init);
		}
 
		private function init(e:Event = null):void 
		{
			removeEventListener(Event.ADDED_TO_STAGE, init);
 
			// entry point
			stage.align			= StageAlign.LEFT;
			stage.scaleMode			= StageScaleMode.NO_SCALE;
			stage.showDefaultContextMenu	= false;
 
			// ** draw minimalist text button **
			opButton			= new TextField();
			opButton.autoSize		= TextFieldAutoSize.LEFT;
			opButton.background		= true;
			opButton.backgroundColor	= 0x000000;
			opButton.defaultTextFormat	= new TextFormat("Tahoma", 14, 0xFFFFFF, true, null, null, null, null, null, 4, 4);
			opButton.selectable		= false;
			opButton.text		= "BROWSE";
			opButton.x			= (stage.stageWidth - opButton.width) * 0.5;
			opButton.y			= (stage.stageHeight - opButton.height) * 0.5;
			addChild(opButton);
 
			// ** button click listener **
			opButton.addEventListener(MouseEvent.CLICK, on_buttonClick, false, 0, true);
		}
 
		/**
		* handle browse or save
		*/
		private function on_buttonClick(evt:MouseEvent):void
		{
			var btn:TextField = evt.target as TextField;
			if (btn)
			{
				if (btn.text == "BROWSE")
				{
					swfFile = new FileReference();
					swfFile.addEventListener(Event.SELECT, on_swfSelect, false, 0, true);
					swfFile.browse([new FileFilter("Flash Movie","*.swf")]);
				}
				else if (btn.text == "SAVE")
				{
					if (swfFile)
					{
						// ** BEGIN ROT128 **
						var j:int = swfFile.data.length;
						while (j--)
						{
							swfFile.data[j] += 128;
						}
						// ** END ROT128 **
						new FileReference().save(swfFile.data, "ActualSWF.swf");
					}
				}
			}
 
		}
 
		/**
		* handle browse, load swf file
		*/
		private function on_swfSelect(evt:Event):void
		{
			swfFile.removeEventListener(Event.SELECT, on_swfSelect);
			swfFile.addEventListener(Event.COMPLETE, on_swfComplete, false, 0, true);
			swfFile.load();
		}
 
		/**
		* handle load, change browse button to save button
		*/
		private function on_swfComplete(evt:Event):void
		{
			swfFile.removeEventListener(Event.COMPLETE, on_swfComplete);
			opButton.text		= "SAVE";
			opButton.x			= (stage.stageWidth - opButton.width) * 0.5;
		}
	}	
}

Step II: Embed Actual SWF In Shell SWF
If you have not done so already, please see “Hiding Assets And Code By Embedding SWF Within Another SWF” for the original discussion on how the technique works.

The following is a MainShell class you can use to embed the ROT128-encrypted SWF:

package
{
	import flash.display.Loader;
	import flash.display.Sprite;
	import flash.utils.ByteArray;
 
	public class MainShell extends Sprite 
	{		
		[Embed(source="ActualSWF.swf", mimeType="application/octet-stream")]
		private static const bytes:Class;
 
		/**
		* REMINDER
		* 
		* MAKE SURE THAT THIS SHELL SWF IS PUBLISHED USING THE
		* ORIGINAL WIDTH/HEIGHT DIMENSIONS OF THE EMBEDDED SWF
		*/
 
		public function MainShell()
		{
			var swf:ByteArray = new bytes() as ByteArray;
			if (swf)
			{
				// ** BEGIN ROT128 **
				var j:int = swf.length;
				while (j--)
				{
					swf[j] += 128;
				}
				// ** END ROT128 **
				Loader(addChild(new Loader())).loadBytes(swf);
			}
		}
	}
}

With the above code, the “ActualSWF.swf” file is embedded into the shell SWF. It is then instantiated as a ByteArray during run-time. ROT128 is then applied to the ByteArray before it is loaded into a Loader object.

Why Do This At All?
Hiding assets and code by embedding one SWF within another SWF is simple to implement and so far, there has not been any report on any decompiler overcoming the protection.

In the original post on the technique, I suggested that you could, if you wish, add another layer of protection by encrypting the embedded SWF just in case a decompiler may in future automatically identify a binary blob and “guess” that it is an embedded SWF (and decompile it separately).

I feel that ROT128 is light-weight and simple enough that can achieve that objective. Remember that the objective here is not to overcome meticulous hacking, but merely to thwart possible attempts to implement automatic extraction and identification of embedded binary blobs as separate SWFs.

The above is only an example of how the concept can be applied. As mentioned in the previous post on ROT128, you can also consider applying ROT128 only to part of the file so that the logic for reversing the encryption could be a little less predictable.

Module SWFs
Although the above mentioned only embedded SWFs, you can definitely apply the same concept to module SWFs that will be loaded into your application during run-time. By applying ROT128 to module SWFs, even if they are obtained via unauthorized means such as via the web browser’s cache, they are non-executable (or will just show a blank screen when run) if the ROT128 encryption is not reversed first.

Stage Size: stage.width / stage.height
The Stage refers to the main drawing area on which all Flash content is drawn. This area will encompass all display objects on the display list since all display objects are ultimately contained within the same Stage object.

The stage.width and stage.height properties give you the dimensions of the current rectangular bounds of the Stage. You can actually get the same results by querying the getBounds() method:

var bounds:Rectangle = stage.getBounds(stage);
trace(bounds.width == stage.width); // true
trace(bounds.height == stage.height); // true

These dimensions only take into account the area occupied by display objects and are therefore not necessarily computed from the origin (coordinates 0,0). For example, if there is only one display object on the display list and this object is 100px wide by 50px tall, the stage.width property returns 100 regardless of the x position of the object. Likewise, the height property returns 50 regardless of the y position of the object.

If you wish the dimensions to take into account the origin (0,0), you can place an invisible dot there:

var dot:Shape = new Shape();
dot.graphics.beginFill(0,0); // black transparent
dot.graphics.drawRect(0,0,1,1); // 1x1
dot.graphics.endFill();
stage.addChild(dot);

If there is nothing on the display list, or if all the display objects on the display list are empty (or of size zero), both stage.width and stage.height return zero (0). That is why if you query these properties at the very beginning of your application before you have anything on the display list, you can expect the value of both properties to be zero.

Screen Size: stage.stageWidth / stage.stageHeight
The stage.stageWidth and stage.stageHeight properties give you the current dimensions of the viewable screen area of the Flash Player (standalone window area or browser plug-in area).

Although these properties are read-write, setting them in your application code has no effect. No error will be thrown, but there will simply be no effect. A change in the value of these properties is typically end-user invoked when the end-user resizes the Flash Player. Your application can get notified of changes in these properties by listening for the Event.RESIZE event, dispatched by the Stage object.

stage.addEventListener(Event.RESIZE, on_stageResize);
 
function on_stageResize(evt:Event):void
{
    trace("screen width : " + stage.stageWidth);
    trace("screen height : " + stage.stageHeight);
}

Adobe’s documentation indicates that if you do not set stage.scaleMode property to StageScaleMode.NO_SCALE, then the stage.stageWidth and stage.stageHeight properties give you the original dimensions of the SWF file, the size that was specified during author-time in the Document Properties dialog box.

However, that is not true.

Contrary to what is stated in Adobe’s documentation, the stage.scaleMode property has no effect on the stage.stageWidth and stage.stageHeight properties. Regardless of the value of the stage.scaleMode property, be it set to StageScaleMode.NO_SCALE or otherwise, the stage.stageHeight will always give you the current height of the screen area occupied by the Flash Player, and the stage.stageWidth the current width. To implement these properties in the way the documentation described would have been wrong in the first place (it would have made the results confusing and less useful), so I would say this is simply a documentation error, not a Flash Player bug.

Knowing the current size of the Flash Player is useful if you wish to create fluid layout that responds to changes in the viewable screen area. These values are also required when checking if a certain display object is within or outside the bounds of the viewable area.

SWF Size: loaderInfo.width / loaderInfo.height
To obtain the original width and height of the SWF file, you must use loaderInfo.width and loaderInfo.height. These are read-only properties and stay constant. The values are hard-coded into the SWF file during compile time (you specify this size during authoring). Adobe’s documentation refer to these dimensions as the “nominal” width and height of the SWF file.

You must wait for the content to be sufficiently loaded before you can query these properties:

loaderInfo.addEventListener(Event.COMPLETE, on_loadComplete);
 
function on_loadComplete(evt:Event):void
{
    trace("swf width : " + loaderInfo.width);
    trace("swf height : " + loaderInfo.width);
}

If you are loading external content:

var ldr:Loader = new Loader();
ldr.contentLoaderInfo.addEventListener(Event.COMPLETE,on_loadComplete);
ldr.load(new URLRequest("module.swf"));
addChild(ldr);
 
function on_loadComplete(evt:Event):void
{
	var ldrInfo:LoaderInfo = evt.target as LoaderInfo;
	if (ldrInfo)
	{
		trace(ldrInfo.width);
		trace(ldrInfo.height);
	}
}

Knowing the nominal dimensions is useful when your application is hosting external module SWFs and you would like to know how much screen space to allocate to a loaded SWF (assuming that the dimensions that are hard-coded into the SWF should be honored). It is also useful if you wish to know the original aspect ratio of the content loaded into a Loader object (the width and height properties of the Loader object may be modified, but the values of loaderInfo.width and loaderInfo.height will always stay the same).

Conclusion
There is generally no correlation between the size of the Stage, the size of the viewable area, and the original size of the SWF.

If you want to know the current viewable area, use stage.stageWidth and stage.stageHeight.

If you want to know the original dimensions of a SWF when it was compiled, use loaderInfo.width and loaderInfo.height.

If you want to know the composite, total area occupied by display objects, you can use the stage.width and stage.height properties (or the getBounds() or getRect() methods).

It is easy to get confused over these three pairs of properties, so hopefully the above has helped to clarify on the differences.

An ActionScript error has occurred: “Cannot access a property or method of a null object reference.”

Quite a cryptic message, especially if you test the module SWF standalone and nothing seems wrong, but the error is thrown when you load the module SWF into a host SWF.

Background of the Problem
When a module SWF is loaded into a host SWF, the constructor of the top-level class of the module SWF will be called before the instance itself (Sprite or MovieClip) is added to the display list. In other words, the stage property will still be null when the class is being instantiated and therefore, referencing a property or method of the Stage object (via the stage property) in the constructor of the top-level class will result in a “null object reference” error.

The same occurs, of course, if the constructor does not reference a property or method of the stage directly, but calls another member (function or get/set property) that does so.

Example of the Problem
Let’s take for example we want the application to be notified when the Stage is resized and will therefore attach a listener to the Stage. The following will work if the SWF is run standalone, but will throw the “null object reference” error if it is loaded into a host SWF:

package 
{
	import flash.display.Sprite;
	import flash.events.Event;
 
	public class Module extends Sprite 
	{
		public function Module()
		{
			init();
		}
 
		private function init():void
		{
			stage.addEventListener(Event.RESIZE, on_stageResize);
			// stage is null, cannot access method of null object, error is thrown
		}
 
		private function on_stageResize(evt:Event):void
		{
			// ** actual application code begins **
			trace("stageWidth: " + stage.stageWidth + " stageHeight: " + stage.stageHeight);
		}
	}	
}

Fix for the Problem
To avoid such an error, simply wait until the display object has been added to the Stage before referencing its stage property. You can do this by listening to the Event.ADDED_TO_STAGE event:

package 
{
	import flash.display.Sprite;
	import flash.events.Event;
 
	public class Module extends Sprite 
	{
		public function Module()
		{
			addEventListener(Event.ADDED_TO_STAGE, init);
		}
 
		private function init(evt:Event):void
		{
			removeEventListener(Event.ADDED_TO_STAGE, init);
			// remove the event listener, because it is possible for the instance
			// to be removed from its container, and re-added to the display list
			// and invoking the event again but we want to call the init method
			// only once per instance of the class
 
			// ** actual application code begins **
			trace(stage); // stage is no longer null
			stage.addEventListener(Event.RESIZE, on_stageResize);
		}
 
		private function on_stageResize(evt:Event):void
		{
			// ** actual application code begins **
			trace("stageWidth: " + stage.stageWidth + " stageHeight: " + stage.stageHeight);
		}
	}	
}

As mentioned above, even if the constructor itself does not reference a property or method of the stage directly, but calls another member (function or get/set property) that does so, or the member calls another member that does so, and so on (you get the idea)… this “null object reference” error will still occur. The referencing may be deeply nested, and therefore, it is probably best to make it a habit to have your top-level class listen for the Event.ADDED_TO_STAGE event before executing other code:

package 
{
	import flash.display.Sprite;
	import flash.events.Event;
 
	public class Module extends Sprite 
	{
		public function Module()
		{
			if (stage) init();
			else addEventListener(Event.ADDED_TO_STAGE, init);
		}
 
		private function init(e:Event = null):void 
		{
			removeEventListener(Event.ADDED_TO_STAGE, init);
 
			// ** actual application code begins **
			trace(stage); // stage is no longer null
		}
	}	
}

FlashDevelop
If you are using the FlashDevelop IDE, the Main.as class file, written in the way described above, will be created automatically for you when you create a new Project using the “AS3 Project” template. However, when writing module classes and compiling them using the Quick Build command, it will be up to you to remember to write them in the way described above (and it is especially for module SWFs that you need to do this).

Reminder:
A Flash application has only one Stage object – display objects in both the host SWF and in any loaded SWF(s) reference the same Stage. Do not confuse stage with the root property.

When using FlashDevelop, building a Project (pressing F8 or CTRL-ENTER) compiles a single SWF using the AS class file that has been flagged as “Always Compile”. If you are building an application that consists of a host SWF and multiple module SWFs, FlashDevelop does not automate the job for you.

Use Multiple Projects
One way to build modules in FlashDevelop is to set up a different Project for each module, with each Project using the same assets but different build configurations (the module class in each Project is flagged as “Always Compile”). The Project for a module class would be set up such that duplicate classes are excluded (via compiler options). However, this can get troublesome and difficult to manage/maintain.

Use Quick Build
What you can do is stick to a single Project – when building the Project, the resulting SWF will be the main (host) SWF. Modules are built using the Quick Build command, accessed via the menu -> Tools -> Flash Tools -> Build Current File (CTRL-F8). This compiles the currently open class file, so you need to open the module class you want to compile and then press CTRL-F8.

The Quick Build command ignores your Project settings, so in order for this to work, you need to insert build options into each module class file. At the top of each module class, insert the following:

/**
* @mxmlc -o=bin/ClassName.swf -external-library-path=AspireUIStandard.swc
*/

The above is only an example, you can also specify other MXMLC options (optimize, default-size, etc.). In the above example, we exclude the classes in the AspireUIStandard.swc from being compiled into the module SWF. If you are using other libraries that are going to exist in the host SWF, remember to exclude them too.

To make testing easy, you can do the following:

/**
* @mxmlc -o=bin/ClassName.swf -l=AspireUIStandard.swc
* //@mxmlc -o=bin/ClassName.swf -external-library-path=AspireUIStandard.swc
*/

-l is alias for -compiler.library-path
Use that when you want to compile the module for testing standalone.

“exclude.xml”
Instead of using the -external-library-path option, you can also use an “exclude.xml” file and the -load-externs option.

Generate an “exclude.xml” from the main Project – in the project settings, compiler options, under “Additional Compiler Options”, add the following:

-link-report exclude.xml

Now build your project (CTRL-ENTER). Verify that the “exclude.xml” is generated and is in the root folder of your Project.

With the “exclude.xml” file generated, you can now use the -load-externs directive for your modules:

/**
* //@mxmlc -o=bin/ClassName.swf -l=AspireUIStandard.swc
* @mxmlc -o=bin/ClassName.swf -load-externs=exclude.xml
*/

This is recommended if the host SWF may not include all the classes in the libraries the modules are using.

uiSWF
Once you have created the module SWFs, you can have your host SWF load them using the uiSWF component (Aspire UI Standard Edition v1.2+). This control is a subclass of uiPane, making it suitable to be plugged in as the content of a uiScrollPane instance (in which case the module should not implement its own wrapper scrollers).