Making Cleaner NASM Code with Macros

Introduction

Cleaner, clearer code is better. It’s easier to debug, it’s easier to read, it’s just plain - better. Assembly code isn’t known for its ability to allow the developer to make their intentions clear in its source code, but we can get closer with some carefully craft macros. Macros are symbols that you can use in your code to represent a block of code. Macros are allowed to take parameters which makes them an extremely flexible and valuable tool in your arsenal. These symbols that you use in your code are swapped out by nasm at the time of assembly for the blocks of code that they represent. If you want to go further in depth to the nasm pre-processor and macros, check it out in the manual here.

Today’s post will be focused on cleaning up the code that we’d written in this previous article to look a little more human.

Revisiting write and strlen

In the previous article “strlen() implementation in NASM”, we’d put together a couple of ways to take the length of a string. This article will assume that we’re already using this code. With this in mind, we can put together a general purpose print function that will display a zero terminated string with the following.

; _print
;
; input
; rdi points to the zero terminated string that 
;     we're printing
;
; output
; none

_print:

  push  rcx       ; start off by preserving the registers
  push  rdx       ; that we know that we'll trash in this
  push  rax       ; proc
  push  rbx

  mov   rcx, rdi  ; rcx = string memory location
  call  _strlen   ; calculate the string's length
  mov   rdx, rax  ; rdx = string length
  mov   rax, 4    ; write() is syscall 4
  mov   rbx, 1    ; we're writing to stdout
  int   0x80      ; execute the call

  pop   rbx       ; restore all of the registers
  pop   rax
  pop   rdx
  pop   rcx

  ret             ; get out

Ok, that’s a nice and neat little bundle. Now, everytime that we want to call this function, we need to write code that looks like the following.

mov  rdi, message    ; load our string into rdi
call _print          ; write the message

Which, isn’t too bad I guess. We can make it look better though. Consider the following code that wraps this code into a macro.

; print - prints a null terminated string
%macro print 1
  push  rdi         ; save off rdi

  mov   rdi, %1     ; load the address of the string
  call  _print      ; print the string

  pop   rdi         ; restore rdi
%endmacro

The syntax here may look a little alien to begin with, but it’ll all make sense in a minute. So, we start the macro block off with a %macro directive. What follows is the name of the macro, in this case print and after that is the number of parameters that this macro will expect (we want one parameter, being the string to print). We have the print code between the directives. You’ll see that rdi gets loaded with %1 which just means “replace %1 with the first thing passed to this macro”. To finish up your macro, you have %endmacro. With that macro defined, you can now print a message to screen by doing this.

print message

This is starting to look a little higher-level now. A bit more “human” on the eyes. Another nifty trick that I’d picked up a while ago was a macro for defining strings. In all of the examples we’ve seen so far, you’d declare strings in the data segment with the following syntax.

section .data

  message db "Hello, world", 0

This is perfectly fine, however we can wrap this string declaration up into a macro of its own as well allowing us to define strings where ever we are. We need to be careful though. Defining a string in the code segment without the appropriate jumps is dangerous as we run the risk of executing the string data. The following macro does this safely.

; sz - defines a zero terminated string
%macro sz 2
  jmp %1_after_def    ; jump over the string that we define
  %1 db %2, 0         ; declare the string
  %1_after_def:       ; continue on
%endmacro

You can see that we’ve declared a macro that expects two parameters. The first parameter is the name of the variable that we declare. This name is also used to formulate the labels that we jump to so that they are unique between string definitions. The second parameter is the actual string data itself. Now that we have both of these macros defined, the following code is perfectly legal and works a treat.

sz message "This is much more interesting than Hello, World!"
print message

Well, this is only the start of what you can accomplish with macros. An exercise to the reader would be to implement your own version of print that prints a new line after it prints the string - you never know, you might even want to call it “println”!

Enjoy.

A Light cron Tutorial

Introduction

cron is the time-based task scheduler for Unix. I think the wikipedia article sums up its description best, so I won’t try and reproduce it:

Cron is the time-based job scheduler in Unix-like computer operating systems. Cron enables users to schedule jobs (commands or shell scripts) to run periodically at certain times or dates.

Today’s post will be a light tutorial in setting up jobs using cron.

Job types

Within the cron system there are two flavors of tasks. The first is at the system level the other is at the user level. The main difference being, the system level tasks (controlled by administrators) are able to run as any particular user. User jobs are setup by the user and installed for the user.

Job installation and modification

Start an editing session of the cron table (crontab) by issuing the following command.

$ crontab -e

You’ll now be looking at the job definitions that are setup. To add a job to the list, you need to add it in the following format.

Minute Hours Day Month DayOfWeek Command [args]

• Minute is specified as (0 - 59)
• Hours is specified as (0 - 23)
• Day is specified as (0 - 31)
• Month is specified as (0 - 12 where 12 is December)
• DayOfWeek is specified as (0 - 7 where 7 or 0 are Sunday)
• Command is the shell command you want to execute

For a system level task, a new field to specify the username is added into this format.

Minute Hours Day Month DayOfWeek Username Command [args]

This will only apply to system level tasks that are added. Operators can be used in conjunction with literal values to short-cut some of the more common tasks.

• Use an asterisk * to define all values for a field
• Use a comma , to separate multiple values for a field
• Use a dash - to define a range

To make some more sense out of the time fields, here are a few examples and when they’d execute.

Out of the box, a cron job will email your local unix account with the results of the job run. If you don’t want to receive this email just pipe the output of your cron command to null, like so.

0 7 * * * test.sh >/dev/null 2>&1

Some short-cut “special variables” that you can use in conjunction with the times that these jobs run look like this (these really clean up the way a crontab reads).

Other maintenance

You can list the cron table with the following command.

$ crontab -l
$ crontab -u user -l

You can remove all entries out of the cron table with the following command.

$ crontab -r
$ crontab -u user -r

That’s it! A nice light tutorial.

strlen() implementation in NASM

Introduction

Seeing so many “Hello, world” concepts for getting up an running in Assembly has annoyed me a little bit. I see people using the $ - msg macro to calculate the length of their string at assemble time. In today’s post, I’ll show you how to measure the length of your string at runtime so you’ll be able to provide the write syscall’s third parameter a little more flexibly.

The logic

The logic behind this procedure is dead-simple. Test the current byte for being null, if it is get out now if its not keep counting! Here’s how the code looks.

_strlen:

  push  rcx            ; save and clear out counter
  xor   rcx, rcx

_strlen_next:

  cmp   [rdi], byte 0  ; null byte yet?
  jz    _strlen_null   ; yes, get out

  inc   rcx            ; char is ok, count it
  inc   rdi            ; move to next char
  jmp   _strlen_next   ; process again

_strlen_null:

  mov   rax, rcx       ; rcx = the length (put in rax)

  pop   rcx            ; restore rcx
  ret                  ; get out

This is just straight-forward memory testing, no great advancements in computer science here! The function expects that the string that requires testing will be in the rdi register. To actually use this function in your application though, you’ll need to transport the result (which sits in rax by the time the function has completed execution) into the register that write expects its length parameter. Here’s how you use your new strlen function (in the Debian scenario).

; strlen(hello)
mov   rdi, hello    ; rdi is the string we want to 
                    ; get the length of

call  _strlen       ; get the length!

mov   rdx, rax      ; rdx now holds the string length
                    ; ready for our write syscall

; write(fd, buf, len)
mov   rax, 4        ; syscall 4 == write
mov   rbx, 1        ; fd = 1 == stdout
mov   rcx, hello    ; the string to write
int   0x80          ; print the string

So you can see that this is quite straight forward. We setup rdx before we setup the rest of the registers. We could have done this the other way around - to be on the safe side, I’ve done it this way as you never know what registers get mowed over in people’s functions. I tried to help this also in the _strlen implementation by saving the only work register that I use rcx. Anyway, that’s how you measure your string.

A more optimal way?

After completing this article, I’d thought about the “brute-forcish” way that I’d crunched out the numbers to derive a string’s length and thought to myself, what if I could just scan the string of bytes - find the null character and subtract this found index from the original starting point. Mathematically I would have calculated the distance in bytes between the start of the string and the NULL character, ergo the string length. So, I’ve written a new string length implementation that does just this and here it is.

_strlen2:

  push  rbx                 ; save any registers that 
  push  rcx                 ; we will trash in here

  mov   rbx, rdi            ; rbx = rdi

  xor   al, al              ; the byte that the scan will
                            ; compare to is zero

  mov   rcx, 0xffffffff     ; the maximum number of bytes
                            ; i'm assuming any string will
                            ; have is 4gb

  repne scasb               ; while [rdi] != al, keep scanning

  sub   rdi, rbx            ; length = dist2 - dist1
  mov   rax, rdi            ; rax now holds our length

  pop   rcx                 ; restore the saved registers
  pop   rbx

  ret                       ; all done!

It may look longer than the first implementation however this second implementation uses SCASB which will be heaps more optimal than my hand-rolled loop.

Enjoy.

Printing a Register's Value in Hex

Introduction

Putting some of the knowledge we’ve picked up in this previous post, today’ss post is going to be about getting the value that sits in a register out on screen. This post will assume that we’re not going to lean on a call like printf, we’re going to do it by hand.

How to attack the problem?

The solution that I present may immediately strike your eye as verbose & long-winded and this is on purpose. We’re going to build something that works to begin with then we can do an analysis of what we’ve written and optimise it later. I’ve split the larger problem of printing a register’s value (in this case we’re printing RAX) into a few smaller problems so as we knock off each problem, we get closer to an overall result. The sub-problems that I have cut this into are:

• Printing a nibble (half a byte or 4bit value)
• Printing a byte
• Printing the register value

So you can see that we’re going to implement a solution by solving these smaller issues top to bottom. Let’s take a look at some code.

Characters and Nibbles

We’re going to print a nibble. A nibble is 4 bits of data spanning values from 0 up to F hexadecimal or 0 up to 15 in decimal. The plan of attack is to isolate this 4 bits in such a way that we can use it as an offset into a string of characters organised from 0 up to F. Here’s the code.

section .data                        
                                     
   hex_chars   db "0123456789ABCDEF"  ; our hex char lookup string
                                     
section .text                        

; it's assumed that the lower 4 bits of al contains
; the nibble that we want to print. rax really needs
; to be zeroed out elsewhere for this to work

_print_nibble:          
                        
  push  rsi                 ; save off any of the register that 
  push  rax                 ; we know that we'll destroy in this
  push  rdi                 ; procedure
  push  rdx            
                        
  mov   rsi, hex_chars      ; load the base address
  add   rsi, rax            ; offset the base address by the value
                            ; we want to print, therefore indexing
                            ; the character

  mov   rax, 0x2000004      ; write() syscall
  mov   rdi, 1              ; write out to stdout
  mov   rdx, 1              ; write 1 byte!
  syscall                   ; make the call
                        
  pop   rdx                 ; restore all of the registers that
  pop   rdi                 ; we saved at the start
  pop   rax            
  pop   rsi            
                        
  ret                       ; get out

The code is documented pretty well, and you can see that the crux of the work is just offsetting the base address of the string by the nibble that we want to print. Nifty. Keep in mind that the registers used here are assuming that you’re compiling for OSX. If you are compiling for another type of unix make sure that the parameters are being passed through the correct registers, otherwise you’ll be segfaulting all the way to the pub!

Stepping up to a byte

Now we want to chain two _print_nibble calls together so that we can print an entire byte out on the screen (0 up to FF). We’ve already got a procedure that prints the lower 4 bits of al out to the screen, all we really need to do is be creative with al so we can print the higher 4 bits first then the lower 4 bits so that the number comes out to the console in the right order! Here’s the code.

_print_al:              
                        
  push  rbx           ; we know that rbx will get a touch
                      ; up here, so save it off
  
  mov   bl, al        ; take a copy of the whole byte and 
  shr   al, 4         ; move the top 4 bits into the lower
                      ; 4 bits of al ready for printing
                        
  call  _print_nibble ; print the lower 4 bits of al 
                        
  mov   al, bl        ; restore al again 
  and   al, 0xf       ; isolate the lower 4 bits of al
                        
  call  _print_nibble ; print the lower 4 bits of al 
                        
  pop   rbx           ; restore rbx
                        
  ret                 ; get out 

This function holds the same assumption as printing a nibble. There can’t be any junk in the higher bits (from al) of rax otherwise this solution will turn to mud.

Going the whole hog!

We’re now able to print any byte we would like, so lets string 8 bytes together to make a 64bit integer that we can print. Again, it’s all about shuffling the value that we want to print around correctly so that the number is written to the console in the correct order. It might be confusing to see pushes and pops inside of the loop that I’ll present, but I re-use these registers to calculate things on the fly. Again, I’ve commented this code pretty verbosely so it should read like a bedtime story. Here’s the code.

_print_rax:          
                     
  mov   rcx, 8      ; there are 8 bytes to print      
                     
_next_byte:          
                     
  push  rax         ; store off the value to print
  push  rcx         ; store off the byte count

  dec   rcx         ; make rcx zero based

  shl   rcx, 3      ; transform rcx so that it will
                    ; hold the number bits that we
                    ; shift out value by so we can
                    ; isolate the correct byte

  shr   rax, cl     ; isolate the correct byte in al     
  and   rax, 0xff   ; make sure there is nothing in 
                    ; the upper parts of rax
                     
  call  _print_al   ; print the value in al
                     
  pop   rcx         ; restore the counter 
  pop   rax         ; restore the value we're printing
                     
  dec   rcx         ; move onto the next byte
  jnz   _next_byte  ; process the next byte if we 
                    ; haven't yet finished

  ret               ; get out!               

The key is byte isolation. Using rcx we can count from the top byte down to the bottom with creative shifting. Now that we’ve implemented all of this code, we can print some boobies to the screen. This is the moment you’ve been waiting for.

_start:                          
                                 
  mov   rax, 0xb000b135b000b135  ; the value to print 
  call  _print_rax               ; print them to screen
                                 
                                 
  mov   rax, 0x2000001           ; exit syscall
  mov   rdi, 0                  
  syscall                       

The output of which should just print “B000B135B000B135” to the console. Yes, there’s boobies in the article, see! Whilst this may not appear to be the most useful function right now, it’ll serve as a very useful debugging tool for us in the future.

Sending email with GMail and Ruby

Here’s a quick little ruby snippet to get you sending email through your gmail account. I had to implement this recently, so I thought I’d make note of it here. You will need the tlsmail gem installed to make this happen. Here’s the code.

require 'tlsmail'                                                              
require 'time'                                                                                                  
                                                                               
from = "me@email.com"                                                     
to   = "someone@email.com"                                                     
pwd  = "SECRET PASSWORD"                                                        
                                                                               
content = <<EOF                                                                
From: #{from}                                                                  
To: #{to}                                                                      
MIME-Version: 1.0                                                              
Content-type: text/html                                                        
Subject: An email for you                                                                
Date: #{Time.now.rfc2822}                                                      
                                                                               
<p>Hello to you!</p>                                                                        
EOF                                                                            

# start up a TLS session (required by GMail)
Net::SMTP.enable_tls(OpenSSL::SSL::VERIFY_NONE)

# send the email
Net::SMTP.start('smtp.gmail.com', 587, 'gmail.com', from, pwd, :login) do |smtp|                                                                              
   smtp.send_message(content, from, to)                                        
end