CS31: Lab 5

This lab should be done with your lab 5 (and beyond) partner:
Lab A Partner list
Lab B Partner list

Lab 5 Goals:

reading and tracing through the execution of IA32 assembly
understanding how IA32 translates to C instructions, data structure access, and function calls
practice with tools for examining binary files
gain expertise in gdb

Lab 5 Intro

You have been sleep walking again, and you wake up on the roof of Parrish Hall. You need to find your way through its maze of floors and out of the building in time for your first class. The problem is that due to construction, there is no stairwell that connects more than two floors. As a result, you need to travel along each floor to find the next open stairwell down to the next floor below. However, there are people or things along your path that can trip you up and impede your progress, forcing you to run back to the roof to try again.

In this assignment, you and your partner are going to receive a binary maze program. Your maze has 5 phases, one for each floor of Parrish Hall (from the roof to out the door). Each floor's phase is a binary puzzle that needs to be solved to move on to the next floor. To solve a puzzle you need to enter a correct phrase on stdin (you can also have your maze read phrases from a file given as a command line argument).

Your goal is to solve all phases/floors of your maze, limiting the number of times you trip-up along the way and have to start all over.

Your maze will automatically notify me every time you trip-up and whenever you have solved a puzzle on a particular floor. In addition, your maze will only run on one of the CS lab machines.

You will submit your lab5 solution in two parts:

Part 1: The Checkpoint (due Thursday Oct. 22 (after break)):

getting past the first two floors of your maze.

Part 2: The complete solution (due Tuesday Nov 3 (after midterm)):

getting past the first four floors of the maze and out the door.
submitting (via git push) a file containing the 4 (or 5) solution strings to solve your maze, and a file containing your write-up of how you solved the puzzle on each floor.
floor 5 is not required. If you solve it, you will receive extra credit, but you must also include a description of how you solved it in your write-up.

Getting Your maze: we will do this together in lab Thurs

Lab 5 Starting point git repo:

Both you and your partner should do:

Get your Lab05 ssh-URL from the GitHub server for our class: CS31-f15
On the CS system, cd into your cs31/labs subdirectory
```
cd ~/cs31/labs
```
Clone a local copy of your shared repo in your private cs31/labs subdirectory:
```
git clone [your_Lab05]
```
Then cd into your Lab05-you-partner subdirectory.
```
  $ ls
  README  maze_ID  maze_how_we_solved_it  soln.txt
```
Next, one of your or your partner should get a maze:
1. In firefox on the CS system, one of you or your partner should enter this url:
```
http://paprika.cs.swarthmore.edu:8000
```
2. Enter your user name on the CS system, and choose Submit.
3. Choose to save the mazeX.tar file in the dialog box that pops up.
4. move the file into your labs/ directory:
```
mv ~/Desktop/mazeX.tar ~/cs31/Labs/Lab05-you-partner/.
```
5. cd into your Labs/Lab05-you-partner directory, and add the mazeX.tar file to your git repo and commit and push it:
```
cd ~/cs31/Labs/Lab05-you-partner/.
ls
  mazeX.tar
git add mazeX.tar
git commit 
git push
```
  Your partener should then to a git pull to get the copy of the mazeX.tar file.
```
cd ~/cs31/Labs/Lab05-you-partner/.
git pull
ls 
  mazeX.tar
```

both you and your partner can untar the mazeX.tar file in your private labs/ subdirectory:

cd ~/cs31/Labs/Lab05-you-partner
ls  # you should see your mazeX.tar file
tar xvf mazeX.tar

if you cd into your mazeX subdirectory, you will see 3 files:
```
cd mazeX
ls
README  maze*  main.c
```
Do not run the maze program yet!
Files in this directory:
main.c: contains the maze program's main function. You can open main.c in vim (or emacs) and see what the code is doing.
maze: contains the maze program binary. This is binary contains a IA32 maze (described below), that you need to solve for this lab.

Checking the status of your maze

You must run the maze lab and the browser connecting to the scoreboard from a CS lab machine

remote access

From firefox running on a CS lab machine, enter this url (you cannot connect to this url from outside our network):

paprika.cs.swarthmore.edu:8000/scoreboard

This information is updated about every 20 seconds. Re-load the page to see the latest information.

Details of the maze lab

Introduction

You can receive up to 71 points out of 66 total for this lab (5 points are extra credit):

Solving the first 4 puzzles are each worth 10 points (40pts total)
Solving the 5th puzzle is worth 5 points (this is not required, and you must include in your write-up a description of how you solved it to receive all 5 points).
Your write-up of how you solved each floor is worth 4 points for each floor (16 points total). Your write-up should be in the file maze_how_we_solved_it in your Lab05-you-partner subdirectory.
The checkpoint is worth 10 points.

Solve Your Maze

set

To kill your maze executable (to make it exit without tripping-up), type CNTRL-C. This way you can run your maze, solve a puzzle on a floor, and then exit and come back later to try the puzzle on the next floor.

You can use many tools to help you solve your maze. Look at the hints section below for some tips and ideas. The best way is to use ddd or gdb to step through the disassembled binary.

Although the puzzles on each floor get progressively harder to solve, the expertise you gain as you move from floor to floor should offset this difficulty.

Once you have solved the puzzle on a floor, I encourage you to run your maze with a soln.txt file containing the input phrases for the floors you have solved. The format of the file should be one phrase per line, in order of the maze floors. Using an input file will help to prevent you from accidentally tripping up in the maze on a previously solved floor. For example:

./maze soln.txt

To avoid accidentally tripping up in the maze, you will need to learn how to single-step through the assembly code and how to set breakpoints. You will also need to learn how to inspect both the registers and the memory states. One of the nice side-effects of doing the lab is that you will get very good at using a debugger. This is a crucial skill that will pay big dividends the rest of your career.

The Write-up

Describe at a high-level what the original C code is doing for each floor. For example, is it doing some type of numeric computation, string processing, function calls, etc. and describe the specific computation it is doing (i.e. what type of string processing and how is that being used?).

Do not list registers and assembly code for this part, but describe what the puzzle on each floor is doing at a higher-level in terms of C semantics. You do not need to reverse engineer the IA32 code and translate every part of it to equivalent C code. Instead, give a rough idea of equivalent C or pseudo code for the main part of the puzzle on each floor. For example, something like "uses an if-else to choose to do X or Y based on the input value Z" is an appropriate right level of explanation. Something like "moves the value at %ebp-8 into register %eax" is way too low-level.

This part of the lab should not be onerous; you should be able to explain each puzzle in a short paragraph or two (maybe with a few lines of C or pseudo code to help explain). I recommend doing the write-ups for each floor as you solve them.

Excessively verbose, low-level descriptions will be penalized, as will vague descriptions; you want to clearly demonstrate to me that you figured out what that floor is doing by examining the IA32 code for each floor in your maze executable.

If you are unable to solve a floor, you can still receive partial credit for it in the write-up part by telling me what you have determined about that floor.

Hints

We do make one request, please do not use brute force! You could write a program that will try every possible input string to find the right one. But this is no good for several reasons:

You lose 1/4 point (up to a max of 5 points) every time you guess incorrectly and the maze trips-up.
Every time you guess wrong, a message is sent to the mazelab server. You could very quickly saturate the network with these messages, and cause the system administrators to revoke your computer access.
We haven't told you how long the strings are, nor have we told you what characters are in them. Even if you made the (incorrect) assumptions that they all are less than 80 characters long and only contain letters, then you will have 26^80 guesses for each floor. This will take a very very long time to run, and you will not get the answer before the assignment is due.

Tools and Resources

weekly lab week 6: resources for examining binary files,
The week 4 and week 5 Thursday Lab pages also have information about using gdb. And Figure 3.30 in the textbook is a nice summary of some useful commands.
my gdb guide has more detailed information about particular gdb commands. See the print (p) and examine (x) examples in the "Common gdb Commands" section in particular.
ddd (or gdb) maze The GNU debugger will be your most useful tool. You can trace through a program line by line, examine memory and registers, look at both the source code and assembly code (we are not giving you the source code for most of your maze), set breakpoints, and set memory watch points.
draw the stack and register contents as you are tracing through code in gdb, and take notes as you go (this will also help you with the write-up part of the lab assignment).
objdump -t maze
This will print out the maze's symbol table. The symbol table includes the names of all functions and global variables in the maze, the names of all the functions the maze calls, and their addresses. You may learn something by looking at the function names.
objdump -d maze
Use this to disassemble all of the code in the maze. You can also just look at individual functions. Reading the assembler code can tell you how the maze works.
Although objdump -d gives you a lot of information, it doesn't tell you the whole story. Calls to system-level functions are displayed in a cryptic form. For example, a call to sscanf might appear as:
```
8048c36:  e8 99 fc ff ff  call   80488d4 <_init+0x1a0> 
```
To determine that the call was to sscanf, you would need to disassemble within gdb.
strings maze
This utility will display the printable strings in your maze.
Also, look at the IA32 Documentation and References for information about particular instructions, registers, the call stack, etc.

Looking for documentation about a particular tool? The the commands apropos and man will help you find documentation about unix utilities, and in gdb the help command will explain gdb commands:

$ man objdump
(gdb) help ni

man

What to submit

Checkpoint: For the checkpoint, you need do nothing to "submit" it. I'll check the scoreboard at the due date to verify whether or not you met the checkpoint.

Complete Solution: For the complete solution you will need to add, commit, and push your solution to your git repo before the due date. Be sure that it contains these three files:

maze_how_we_solved_it: the write-up part for your maze.
soln.txt: your maze's solution input file: ./mazeX soln.txt
maze_ID: this file just lists your maze ID

Submit

cd ~/cs31/Labs/Lab05-you-partner/
git add soln.txt
git add maze_ID
git add maze_how_we_solved_it

git commit
git push

Git Help

CS31 Lab 5: Binary Maze

(or getting out of Parrish Hall in a CS31 kind-of way)

Lab 5 Goals:

Lab 5 Starting point git repo:

Files in this directory:

Introduction

Solve Your Maze

Tools and Resources