Flat Assembler Extras

These page contains various include files, interesting macros, and modifications to FASM.

Sections

1. Macros and Include Files
2. IDE Modifications
3. Gems
   1. Code Obfuscation
   2. Self-Encrypting Code
4. Past Versions

Macros and Include Files

The base package for FASM contains many useful macros to construct Windows resource sections, import tables, etc. The include files also cover the base of the Win32 platform. To complement this base set, I created another package that contains more macros, and definitions for more Win32 features. You can download it here.

Extract the package to the root of your FASM installation.

The package also contains INCLUDE/EQUATES/TLHELP32.INC, which is a hand-translated include file of the Toolhelp APIs (tlhelp32.h).

The INCLUDE/WIN32AM.INC and INCLUDE/WIN32WM.INC are my minimal include files. These are virtually identical to the INCLUDE/WIN32A.INC and INCLUDE/WIN32W.INC files in the base FASM package, except mine don't automatically include everything under INCLUDE/EQUATES/. This speeds up compilation.

The INCLUDE/MACRO/macros.inc is a macro file with many useful macros for debugging, such as quickly showing a message box with some integer value. Here is a complete example:

; using macros
; 04.07.2008

format PE GUI 4.0
entry start

include "%include%/win32a.inc"
include "%include%/macro/macros.inc"    ; include our magic macros file

section ".code" code readable executable
start:
        push    ebx esi edi

        ;
        ; Show a fixed string messagebox.
        ;
        showmsg "Hello!"

        ;
        ; Show a simple integer.
        ;
        mov     ebx,-5
        showint "value of ebx in decimal",ebx
        showuint "value of ebx in unsigned decimal",ebx
        showhex "value of ebx in hexadecimal",ebx

        ;
        ; Show a string pointer.
        ;
        mov     ebx,Hello
        showstr "string pointed to by ebx",ebx
        msgbox  ebx

        ;
        ; Show a custom-formatted message.
        ;
        mov     ebx,Hello
        mov     esi,10
        mov     edi,17
        showfmt "ebx is '%s',esi is %u, and edi is %u",ebx,esi,edi

        ;
        ; Set the last error to 'Access denied.'
        ;
        stdcall [SetLastError],5
        lasterr

        ;
        ; The following macros generate simple code to convert a 7-bit ASCII character to uppercase/lowercase.
        ;
        mov     al,'a'
        ucase   al      ; al is now 'A'
        lcase   al      ; al is now back to 'a'


        pop     edi esi ebx

        stdcall [ExitProcess],0

section ".data" data readable writeable import
        library kernel32,"kernel32.dll",user32,"user32.dll"
        include "%include%/api/kernel32.inc"
        include "%include%/api/user32.inc"

        ;
        ; Use the DATE and TIME variables that were defined by macros.inc to record the date and time this file
        ; was compiled at. Credits to Privalov for the date conversion macros.
        ;
        Hello   db      "hallo! this was compiled at: ",DATE," ",TIME,0

Running this code will produce a series of message boxes displaying the needed values.

IDE Modifications

This section contains some modifications I made to the FASM IDE for Windows (FASMW.EXE). Notably:

1. Add configurable, external debugger support. You configure the path to your debugger, press F8, and the IDE will automatically compile the file, and launch the debugger.
2. Display the name of the file being currently editted in the program's title bar.
3. Default all "Save modified file?" message boxes to 'Yes'. For some reason, the author decided there are times when you don't want to save your changes by default. This differs from other applications which always pick the safest option: save your work.
4. Show the length of currently selected text in the status bar. This is useful in measuring string lengths quickly, and then using them somewhere in the code.
5. Map Ctrl-W to close file. This is a common keyboard shortcut that FASMW IDE does not have.
6. Unmap Escape from closing the file. I frequently press Esc to close some dialog, and end-up closing the IDE by mistake.
7. Change the GUI font to Tahoma, instead of Win95-esque MS Sans Serif.

You can download the modified FASMW.EXE binary file here (55 KB), version 0.93.15.1 (that is, the 0.93.15.0 that comes with FASM 1.67.26, plus these modifications).
Alternatively, you can compile it yourself. Get the base FASMW 1.67.26 distribution, and apply the following diff file using GNU's patch utility. The patch is relative to FASM/SOURCE, so apply the patch from that directory, like so patch.exe -p3 <fasmw-0.93.15.1.patch. After applying the patch, simply recompile SOURCE/IDE/FASMW/FASMW.ASM.

Gems

This section contains various gems and tricks possible with FASM, mostly thanks due its advanced macro capabilities.

Code Obfuscation

This trick involves creating macros that override the default behaviour of various common instructions, such as jmp, call, add, etc. The overriden instruction preserves the functionality of the original instruction, with some extra junk that makes the disassembly much harder to read and analyze, even for advanced disassemblers such as IDA.

Consider the following macro:

macro add dest,src {
    local .._add,.._over,.._quit
    jmp  .._over
    db $E9
  .._add:
    add dest,src
    jmp .._quit
  .._over:
    jmp .._add
    db $EB
  .._quit:

In this macro, we create a junk jmp ($E9) opcode just before the actual add instruction. When a disassembler processes this code, it will miss the add instruction, and actually disassemble some junk jump that makes no sense. Obviously, the code size blows up and performance decreases with this kind of substitution macro.

I originally pioneered this technique as part of the protection in Lokomotiv trainer engine project. Here is the full set of substitution macros that I created for it:

macro jmp dest {
    push dest
    retn
    db $E9
}
macro call dest {
    local ..ret
    push ..ret
    jmp  dest
    ..ret:
}
macro mov dest,src {
    local .._mov,.._over,.._quit
    jmp  .._over
    db $EB
  .._mov:
    mov dest,src
    jmp .._quit
  .._over:
    jmp .._mov
    db $74
  .._quit:
}
macro add dest,src {
    local .._add,.._over,.._quit
    jmp  .._over
    db $E9
  .._add:
    add dest,src
    jmp .._quit
  .._over:
    jmp .._add
    db $EB
  .._quit:
}
macro sub dest,src {
    local .._sub,.._over,.._quit
    jmp  .._over
    db $75
  .._sub:
    sub dest,src
    jmp .._quit
  .._over:
    jmp .._sub
    db $0F,$85
  .._quit:
}
macro cmp dest,src {
    local .._cmp,.._over,.._quit
    jmp  .._over
    db $0F,$84
  .._cmp:
    cmp dest,src
    jmp .._quit
  .._over:
    jmp .._cmp
    db $7A
  .._quit:
}

Simply paste these macros into a separate file and include it before your code, and then assemble your program with FASM as usual. Disassemble the output file to see the abomination.

Self-Encrypting Code

This is another technique I created as part of the protection for the Lokomotiv trainer engine project in early 2004. Coincidentally, someone had the same idea on the FASM board a couple of months later.

This technique involves FASM's ability to manipulate the bytes of the code it had already assembled. In this case, we use a simple cryptor to encrypt a chunk of assembled code during compile time. At run-time, we run a short loop that decrypts the code in memory.

Consider a simple Hello World message box, with the encrypting macro setup:

; selfencrypt
; 04.07.2008

format PE GUI 4.0
entry start

include "%include%/win32a.inc"

;
; This is the encryption macro.
; It is a simple XOR with 0xAA (10101010 in binary).
;
macro encrypt dstart,dsize {
    local ..char,..key,..shift
    repeat dsize
        load ..char from dstart+%-1
        ..char = ..char xor $AA
        store ..char at dstart+%-1
    end repeat
}

section ".code" code readable writeable executable
start:
        ;
        ; This will be the only non-encrypted part of the code.
        ; Here we will decrypt the code at run-time.
        ;
        mov     edx,real_start
        xor     eax,eax
        mov     ecx,code_size
@@:     xor     byte [edx],$AA
        inc     edx
        loop    @B

real_start:
        ;
        ; Everything from here on will be encrypted.
        ;
        stdcall [MessageBox],0,HelloWorld,HelloWorld,MB_ICONASTERISK

        stdcall [ExitProcess],0

        ;
        ; Encrypt everything from real_start to here.
        ;
        display "Encrypting code... "
        code_size = $ - real_start
        encrypt real_start,code_size
        display "done",13,10

section ".data" data readable writeable import
        library kernel32,"kernel32.dll",user32,"user32.dll"
        include "%include%/api/kernel32.inc"
        include "%include%/api/user32.inc"

        HelloWorld      db      "Hello World!",0

One particular thing to note is that the .code section is marked as writeable. This is needed so the code can be decrypted and written back at run-time.

You can find a more elaborate encryption algorithm as part of Lokomotiv trainer engine.

Past Versions

This sections contains an archive of past versions of FASM. The author used to keep a limited archive here, but it is no longer maintained. Here is mine (thanks to FASM forum members for helping me build it):

created 03.07.2008, updated 30.07.2008