Lab 1: Linux Setup

When you're done with this lab you will have done the following things:

Install Git on WSL2
Set up your Linux for running ARM assembly.
Practice basic Linux command lines.
Fix a broken image by hacking the raw binary file

The very last task does not need to do on Linux, so it can be done even if you are having issues that delay the setup of your WSL2.

Part 1: Git on Linux

Goals of this section:

Launch Linux in WSL2.
Install and practice Git

If you haven't yet, please complete the prelab.

Launch your Linux in WSL2, and it's time to play around Linux with a terminal. For the rest of this lab, you're going to use a number of linux commands. Here's a quick reference for some of them:

cd <dir>: change directory. For example, cd foo is like opening the folder "foo" and going inside. cd .. goes back up a directory.
ls: show a list of the files in the current directory
cat <file>: display the contents of a file.
Up arrow: repeat the previous command
<tab> (or double <tab>): auto-complete filename or path
<ctrl> + c: terminate the current running command

Also, in order to run things as an administrator (for example, to install programs), you need to use a command called sudo. This temporarily turns you into an admin called root. Try it!

user@hostname ~ $ whoami
username
user@hostname ~ $ sudo whoami
root

Install Git

Next, you need to install the git client so you can get your lab and homework materials. Use apt to install it!

user@hostname ~ $ sudo apt install git

NOTE: your Linux may already have Git installed. If it does, running this command will result in a message such as:

git is already the newest version

Use Git

Clone your class repository

Clone your repository using a command like this, replacing <username> with your RHIT username. NOTE: <username> appears twice; replace it both times. Use the git clone command:

git clone ssh://<username>@gitter.csse.rose-hulman.edu:13022/srv/repos/2324b-csse132-<username>

Use your RHIT password when asked for a password.
NOTE: GIT may ask you if you want to accept a key. Type "yes" to accept.

Once it's checked out, use the cd command to go into the directory, and the ls command to show your repository's contents. HINT: you can type part of the command (like "cd 1819" and then hit tab to auto-complete the directory).

user@hostname ~ $ cd 2324b-csse132-username/
user@hostname ~/2324b-csse132-username $ ls
lab1
user@hostname ~/2324b-csse132-username $

Open the Git folder in Windows File Explorer

To open your folder/files under your Linux OS. Open the Windows File Explorer and type the command below in the PATH bar (the one on the left) NOT in the search bar (the one on the right).

\\wsl$

From there, you can find Ubuntu-20.04 or Ubuntu. Your home folder will be /home/<user>. Under the home folder, you can find your course repo folder named 2324b-csse132-<username>.

Alternatively, in your WSL2 (Ubuntu), you can first go to your course repo by typing

cd 2324b-csse132-username/

Then you can type the following command to open the folder in Windows File Explorer:

explorer.exe .

You will need to drag and drop files from this folder to GradeScope in the future. So it is highly recommended bookmarking this folder.

SAVE A SCREENSHOT TO SHOW YOUR INSTRUCTOR LATER

No worries about calling out your instructor for signature yet. Save a screenshot of opened folder for now. When you finish more items, you can show to your instructor all at once. -->

Part 2: Get Linux Ready for ARM Assembly

Install Toolchain and QEMU

Run the following command in order to install necessary libs and packages.

Update system.

  sudo apt update -y

Install the ARM cross-compile tools.

  sudo apt install -y gcc-arm-linux-gnueabihf binutils-arm-linux-gnueabihf binutils-arm-linux-gnueabihf-dbg

Install the emulator (QEMU) to run ARM.

  sudo apt install -y qemu-user qemu-user-static gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu binutils-aarch64-linux-gnu-dbg build-essential

Compile and Run an ARM program

In Linux, navigate to the hello_ARM folder under lab1 folder under your git repo. This can be done with the following command:

 username@hostname ~ $ cd  2324b-csse132-username/lab1/hello_ARM

Using ls command, you can check the files under this directory:

username@hostname ~/2324b-csse132-username/lab1/hello_ARM $ ls
Makefile hello.s

Then type make to compile the ARM source code. Usually, you will see output like this

username@hostname ~/2324b-csse132-username/lab1/hello_ARM $ make
arm-linux-gnueabihf-as  hello.s -o hello.o
arm-linux-gnueabihf-ld -static hello.o -o hello

Now you can run the executable file by typing make run. Your setup is successful if you can see the message below:

Hello, ARM32!
If you see this message, your ARM env setup is successful!!

SAVE A SCREENSHOT TO SHOW YOUR INSTRUCTOR LATER

No worries about calling out your instructor for signature yet. Save a screenshot of the "hello message" (like using SnapShot) for now. When you finish more items, you can show to your instructor all at once.

Part 3: Learning and Practicing Linux Command lines

Open a web browser and go to the bandit instruction page using the link below:

http://overthewire.org/wargames/bandit/

Follow the instructions and get into level 5. After finishing each level, save the password on your computer (e.g., in notepad). You will need to fill tis info in the verification sheet.

Part 4: Fix an Image

Finding the image: Open File Explorer and type \\wsl$ then enter. You should be able to see "Ubuntu" or "Ubuntu-20.04" (If you don't, launch Ubuntu in Windows Terminal first). Keep navigate to the lab1 folder with this path: "Ubuntu" or "Ubuntu-20.04" -> /home/<your_username>/2324b-csse132-<your_username>/lab1. There you can find the lab1_broken_pic.png To make this picture file in Linux easy to access from Windows, copy it to the Desktop (or anywhere you can find).

In this part, you will need to tweak the data of an image file to help fix a broken image. To modify the raw data of a file, you need special tools to do that. Frhed is a free binary file editor available on Windows. Follow the link below to download the tool:

Frhed Download Link

Usage:

Launch the tool: Type its name FrHed in the Windows search bar and click to open
Open a file: Inside the tool, click on File tab on the top left corner and open any file you want.
Edit data: Use arrow keys (or mouse) to navigate to the hex number you want to edit, and type the desire hex number. To save the change, press Ctrl + s.

Wrong Format

PNG defines a certain format that a picture file has to follow. If a picture does not strictly follow this format, computers can not recognize it correctly, and thus fail to open it as a picture. This is what happened for this picture.

To fix it, you need to first understand the format specs of PNG. Check the PNG Format Specs page and particularly focus on the File Header section.

Now, open the lab1_broken_pic.png (the one you copied to Desktop), and inspect the header (the few bytes at the beginning) to see if it matches the format specs in the Wiki page. Fix the incorrect byte.

If you successfully correct the header, the picture can be opened as a picture to view. However, since the size information is incorrect, when you open this picture in apps like Paint, you will see some white margin underneath the picture.

Wrong Size

When opening the picture, you will see extra white space below the picture. That's because the size specified in the file is not correct, specifically the height is too big. (You can find the size information by right clicking the file -> Properties -> Details Tab.)

Check again the PNG Format Specs to find the bytes that define the height.

Hint: After the header, comes a series of chunks, each of which conveys certain information about the image. The height is defined in the IHDR chunk, the very first chunk of the file.

Once you find the bytes that define the height, change it from 666 to 410. First, convert these two numbers to hex and then edit the bytes accordingly.

If you did that, your image file should have the correct size. If you open it in Paint, you will see the white margin removed. If you are using Linux as the host OS on your laptop, after you modified the size, the picture will appear to be broken again because the CRC is incorrect. However, if you use Windows, the picture is still viewable because Windows doesn't care about CRC.

Fix the CRC (Optional)

The reason it should break is because the software should notice we edited (corrupted) the file so it should consider the file is not safe. The way the computer detects this problem is to use certain bytes in the file to calculate a validation code, called CRC (cyclic redundancy checksum). It will compare the computed result with the checksum stored in the file. If the result doesn't match, it knows the file is corrupted. In our case, the CRC for the IHDR chunk is not correct given the modified height info. To find the the CRC, pay attention to the "offset" shown at the bottom left corner of the app: the first byte of CRC is at the offset/address 0x1D.

We need to re-calculate the CRC. Once we know which bytes we need to use to generate the new CRC, we can simply use this website CRC calculator to calculate new CRC. Based on the specs, we know the CRC for this chunk is calculated over the chunk type and chunk data (Hint: from offset 0xc to 0x1c). To use this website, you need to select CRC-32 first. Then you need to copy the bytes using the format like 0x31 0x32 0x33 0x34 ..... Once you calculate the new CRC, update this new CRC in the file.

Once you have done that, the picture will have the correct CRC and can be opened on Linux. On Windows, there is no visual difference after fixing the CRC.

SHOW YOUR INSTRUCTOR

Now it is a good time to call your instructor to check all the items at this point off the Instructor Verification Sheet.

Finishing the Lab

Scan and Upload the signed instructor verification sheet to GradeScope.