History

SourceCodeOrganistation

This section gives an introduction into the source code of Blitzableiter.

Using Blitzableiter

Processing of an SWF file using Blitzableiter is straight forward. After referencing the assemblies, the name space Recurity.Blitzableiter.SWF is available. An instance of the class SWF must be created, which offers the following basic methods for processing:

  • SWFFile.Read( Stream ) instructs the class to read and parse the SWF file through the stream provided. The Stream must be able to seek. During the parsing, the application settings decide on the criticality of encountered issues. Commonly, the exception SwfFormatException is thrown in case of violations of the specification. After the method finished, the source stream can be closed and is no longer needed.
  • SWFFile.Verify() performs verifications after the full file is read. It primarily focuses on the Bytecode verification, as other format violations would have been detected during Read(). The method returns a boolean, indicating whether the verification was passed (True) or not (False).
  • SWFFile.Write( Stream ) instructs the class to write a completely new SWF file, based on the information the class carries. The method only supports writing uncompressed SWF files.

Version Dependence

Since the SWF format elements are heavily version dependent, every Blitzableiter class that represents a format element has a public property called Version. The property is initially set to the version of the SWF stream when it was read. Setting the Version property sets a new version before writing to a stream. The version number will propagate to all sub-elements of the element it was set for and will be used for size calculations as well as for rendering the output stream and AVM Bytecode.
To guarantee that every format element exposes this property, all classes implementing a format element must implement the interface ISwfElement. To ensure that the version information is always propagated when a new instance of a format element class is created, inheriting from AbstractSwfElement is highly recommended.

Tag Handlers

Reading, verification and writing of individual tags is performed by Tag Handler classes. Every tag handler class inherits from AbstractTagHandler and is created by TagHandlerFactory. The tags of the current SWF file are exposed as array of tag handler instances through an iterator of SWFFile. For example, the first tag of the file can be accessed through swfFileInstance[0]. Every tag handler exposes a public property called Code, which provides an array of AVM code blocks (currently only AVM1). If the tag did not contain AVM code, the array will have a length of 0. This property should be used for easy iterative access to all code blocks attached to the tag.

AVM1 Code

Currently, all code blocks are of the type AVM1.AVM1Code. The class provides methods for accessing the individual instructions, which all inherit from AbstractAction. Every AVM1 instruction is represented by its own class within the Recurity.Blitzableiter.SWF.AVM1 name space.
AVM1Code also allows code modifications on the instruction level, through the methods RemoveAt and InjectAt. The methods will automatically adjust branch target offsets within the modified code blocks, ensuring that the code will be functionally equivalent afterwards, except for the explicit modification itself.
Due to the limitation of AVM1 branches using singed 16 Bit offsets, injection of code can cause an AVM1ExceptionByteCodeFormat exception to be thrown, if the branch target overflows when being increased to account for the additional code.

AVM1 Modifications

The name space Recurity.Blitzableiter.SWF.AVM1Modifier contains the class Modification, which can load a text representation of AVM1 instructions and arguments from a text file, which can be thought of as assembly listing. A modification can be applied to a code block, allowing easy patching of the AVM1 code within.
This part of the code tree is likely to change in the future.

Format Elements

Blitzableiter contains a variety of classes representing format elements of the SWF file format. They generally expose a Parse and a Write method, as well as a Length property, which returns the size of the rendered element in bytes. The format element classes are named after their respective entries in specification.
The following elements are currently available:

  • ButtonCondAction
  • ButtonRecord
  • ButtonRecord2
  • ClipActionRecord
  • ClipActions
  • ClipEventFlags
  • CXFormWithAlpha
  • FilterList
  • MATRIX
  • RECT
  • RGB
  • RGBA

Additional format element classes will be introduced in future versions.

Logging

All Blitzableiter classes use the log4net framework to perform logging. The program using Blitzableiter is responsible to initialize log4net and to configure the logging level. Generally, the following convention is used for the log levels:
  • Debug level messages contain detailed information on the processing, which help developers to debug the library.
  • Info level messages only offer a small subset of processing information and can be used in integration.
  • Warn level messages convey security relevant warnings about format inconsistencies that didn't warrant an exception or where the strict checking has been turned off through the engine's configuration settings.
  • Error level messages are generated together with exceptions that stop the parsing process.
  • Fatal level messages are generated for obvious faults in Blitzableiter's own code logic, e.g. when a rendered element fails validation.

Also available in: HTML TXT