Final Project Solution

Note: This is an individual project and you must complete the work independently. Since this is the final project (due on the final's week), you are not allowed to use grace days on the submission. Late submissions will lose 50 points per day. Please submit your work on time!

This project is worth 125 points (100 points for the code and 25 points for the documentation).

Objectives

    1. Working on a project that utilizes a broad spectrum of knowledge from this course

    2. Using various forms of indirect addressing

    3. Passing parameters on the stack

    4. Extensive interaction with arrays

Description


Alex and Sila are espionage agents working for the Top Secret Agency (TSA). Sometimes they discuss sensitive intelligence information that needs to be kept secret from the Really Bad Guys (RBG). Alex and Sila have decided to use a simple obfuscation algorithm that should be good enough to confuse the RBG. As the TSA’s resident programmer you’ve been assigned to write a MASM procedure that will implement the requested behavior. Your code must be capable of encrypting and decrypting messages (and meet the other requirements given in this document). This final project is written less like an academic assignment and more like a real-life programming task. This might seem daunting at first but don’t despair!

Algorithm Details
Alex and Sila’s algorithm is a simple substitution cipher. If you are not familiar with substitution ciphers, I suggest reading the Wikipedia page (available here (http://en.wikipedia.org/wiki/Substitution_cipher) ). For this implementation, the key consists of 26 lowercase English letters. The following example demonstrates the obfuscation algorithm that Alex and Sila are requesting.

Suppose that you are provided the following 26 character secret key: efbcdghijklmnopqrstuvwxyza. Each character listed in the key corresponds to a character from the English alphabet. In other words, the key is a map that tells you how to take the original text (also known as plaintext) and replace each letter with the encrypted character.

In order to understand the key, consider the alphabetical arrangement of the English alphabet beginning with a, b, c, d, e, f, (and so on).

Now reconsider the key, which starts with e, f, b, c, d, g, (and so on).

Using the key from above, we can map each letter as follows:


Original Character --> Encrypted Replacement

a --> e

b --> f

c --> b

d --> c

e --> d
f --> g

g --> h

h --> i

i --> j

(some entries skipped)
x --> y

y --> z

z --> a

For example, every “a” in the original message is to be enciphered as an “e”. Every “b” in the original message should be replaced with the letter “f”. Each character in the original message maps to a specific replacement character.


Now suppose that you are trying to encrypt the following plaintext message:

the contents of this message will be a mystery.

Using the secret key from above, the corresponding ciphertext is:

uid bpoudout pg uijt ndttehd xjmm fd e nztudsz.

Note that only the letters have been changed! Other aspects of the message such as punctuation and spacing should be be left unchanged. In order to decrypt the message, you can use the same key (in reverse) to process the ciphertext and convert it to plaintext.
The key will always consist of exactly 26 characters (containing every letter of the English alphabet arranged in a random order). A character can NEVER appear twice within the same key.

General Overview

You are going to be writing a MASM procedure named compute which will be called from a MAIN procedure (that you do not control).

Your MASM procedure has several modes of operation, depending on how it is called.

Please read this overview and then look at the Example Usage section below.

The compute procedure will be capable of several operations, namely:

A default "decoy" mode of operation where the procedure accepts two 16-bit operands by value and one operand by OFFSET. The procedure will calculate the sum of the two operands and will store the result into memory at the OFFSET specified.

Accepts 3 parameters on the stack


16 bit signed WORD operand


16 bit signed WORD operand


32 bit OFFSET of a signed DWORD (the sum will be placed into the specified DWORD)

An encryption mode


Accepts 3 parameters on the stack


32 bit OFFSET of a BYTE array (this array contains a 26 character key)


  32 bit OFFSET of a BYTE array (this array contains the plaintext message to be encrypted)

  32 bit OFFSET of a signed DWORD (the dereferenced value initially contains the integer -1)

Note that the plaintext message will be in a BYTE array that ends with a NULL character (indicating the end of the message)


This operational mode will encrypt the requested message. By the time your function returns, the original plaintext message array will be overwritten with the correctly encrypted message.

A decryption mode


Accepts 3 parameters on the stack


32 bit OFFSET of a BYTE array (this array contains a 26 character key)


32 bit OFFSET of a BYTE array (this array contains the encrypted message that is to be decoded)


32 bit OFFSET of a signed DWORD (the dereferenced value initially contains the integer -2)


Note that the encrypted message will be in a BYTE array that ends with a NULL character (indicating the end of the message)

This operational mode will decrypt the requested message. By the time your function returns, the encrypted characters (inside the array) will be overwritten with the decrypted message.

A key generation mode (OPTIONAL) - THIS SPECIFIC MODE IS EXTRA CREDIT


Accepts 2 parameters on the stack


32 bit OFFSET of a BYTE array (this array contains space for exactly 26 characters)


32 bit OFFSET of signed DWORD (the dereferenced value initially contains the integer -3)


In this mode, your code will utilize the Irvine random number library. You must generate a 26 character string containing all the lowercase letters of the English alphabet.

The letters must be arranged in a random order.


If this function is called multiple times, the order of the characters must be different each time.


Your randomly generated character string will be placed into BYTE array specified by the stack parameter.


Example Usage of Your Procedure

From the description above, it may not be clear how the various modes of operation are selected. This section provides some examples that should provide clarification.

Recall that you will not be providing a .data segment in your submitted code. However, it is fine to write a .data segment while you are testing your code.


The decoy mode (as called from the main procedure):


.data


operand1
WORD
46
operand2
WORD
-20
dest
DWORD
0
.code

    • inside the MAIN procedure push operand1

push operand2 push OFFSET dest call compute

    • currently dest holds a value of +26
mov    eax, dest

call    WriteInt    ; should display +26
An example of encryption mode (as called from the main procedure):


.data


myKey
BYTE
"efbcdghijklmnopqrstuvwxyza"
message
BYTE
"the contents of this message will be a mystery.",0
dest
DWORD
-1
.code

    • inside the MAIN procedure push OFFSET myKey

push OFFSET message push OFFSET dest call compute

    • message now contains the encrypted string
mov    edx, OFFSET message

call    WriteString

;; should display "uid bpoudout pg uijt ndttehd xjmm fd e nztudsz."




An example of decryption mode (as called from the main procedure):


.data


myKey
BYTE
"efbcdghijklmnopqrstuvwxyza"
message
BYTE
"uid bpoudout pg uijt ndttehd xjmm fd e nztudsz.",0
dest
DWORD
-2
.code


    • inside the MAIN procedure push OFFSET myKey
push
OFFSET
message

OFFSET
dest
push


call
compute
;; message now contains the decrypted string

mov    edx, OFFSET message

call    WriteString

;; should display "the contents of this message will be a mystery."




An example of key generation mode (as called from the main procedure). As noted above, you are not required to implement this mode unless you want the extra credit.


.data



newKey
BYTE
26
DUP(?)
dest
DWORD
-3

.code



    • inside the MAIN procedure push OFFSET newKey
push OFFSET dest call compute

    • newKey now contains a randomly generated key.

    • The key will contain all 26 letters of the alphabet
    • (arranged in a random order).

    • Note that newKey is not NULL terminated.





Example Output


Decoy:

Should display '+26':
+26

Encryption:

Should display 'uid bpoudout pg uijt ndttehd xjmm fd e nztudsz.':

uid bpoudout pg uijt ndttehd xjmm fd e nztudsz.

Decryption:

Should display 'the contents of this message will be a mystery.':

the contents of this message will be a mystery.

Key generation: (Extra credit)

Should display a 26 character long string containing a-z with no repeats:
wxacbqjlygehvdtnupisrfkomz


Additional Requirements

    1. Your code must operate in the manner shown in the examples (accepting the parameters on the stack).

    2. I will always interact with your code by calling the compute procedure.

    3. The main procedure from your code will not be used! Instead, I will verify the functionality of your procedure by writing my own main procedure and calling your compute procedure (in multiple ways) to test it.
    4. Your code cannot include a .data segment! Instead, any memory that you want to utilize must be allocated from the stack.

    5. Your procedures are not allowed to reference .data segment variables by name (this is implied by requirement #4).
    6. Procedures are allowed to use local variables if you choose (section 8.2.9 in the textbook). The alternative is for you to manually adjust ESP (allocating an area of memory on the stack that you can use within your procedure).
    7. All procedure parameters must be passed on the system stack.

    8. Each procedure will implement a section of the program logic. Your code must be modularized into at least 4 procedures (not including main). In other words, your compute procedure must divide the work into various sub-procedures (that are called from inside compute). The specifics of how you divide the work and achieve this task are up to you.
    9. Parameters must be passed by value or by reference on the system stack as listed above.

    10. You are never allowed to corrupt memory by accessing arrays at invalid indices. In particular, the encrypted messages and decrypted messages are stored in arrays that terminate with a NULL character. The NULL character must be left intact.
        11. The program must use appropriate addressing modes for array elements (no hard-coded array names).

        12. The random number generator must be properly seeded using Randomize

        13. Each procedure must have a procedure header that follows the format discussed during lecture.

        14. The code and the output must be well-formatted.

        15. The usual requirements regarding documentation, readability, user-friendliness, etc., apply.

        16. Your code must not enter any infinite loops, cause a segmentation fault, or result in any other undefined behavior.

Notes

    1. DO NOT put this off - it is the final project for this course and serves as the final exam.

    2. Assume that the messages (to be encrypted or decrypted) could be up to 50,000 bytes long (including the NULL character). 3. The key is exactly 26 characters long and is never NULL terminated.

    4. The parameters will ALWAYS be pushed to the stack in the exact order shown in the examples above.

    5. The Irvine library provides procedures for generating random numbers. Call Randomize once at the beginning of the program (to set up so you don't get the same sequence every time), and call RandomRange to get a pseudo-random number. (See the lecture slides)

    6. For this program you can assume that the plaintext message will not contain any capital letters. That makes the program easier to implement.
    7. If you choose to use the LOCAL directive while working on this program be sure to read section 8.2.9 in the Irvine textbook. LOCAL variables will affect the contents of the system stack!


Extra Credit Options
(1 pt) Add a comment that contains EXACTLY ONE TA name at the beginning of the program. If that TA happens to be your grader, then you get the points :)

(2 pts) Ensure that the "decoy" mode correctly returns the sum of ANY signed 16 bit numbers


For example, if I sum these two 16-bit numbers: (-32768) + (-32768) I should receive the value (-65,536) (stored in the 32 bit variable).

(8 pts) Implement the key generation mode as described in the documentation.


Project Write-Up

Part 1: Summarize your work in a well-written report. You should proof-read your report and ensure that the writing meets professional standards. Use images, charts, diagrams or other visual techniques to help convey your information to the reader.

Be sure to address the following points and answer these questions:

How did you break up your code into multiple procedures (i.e. what was your strategy to separate the code into pieces)?


Did you run out of general purpose registers when implementing your design? If so, what steps did you take to work around the problem?

Is there anything you would implement differently if you were to re-implement this project?


What were the primary challenges that you encountered while working on the project?


Besides the textbook, were there any particular resources that you would recommend to future students in this course?


Part 2: If you chose to implement any extra credit tasks, be sure to include a thorough description of this work in the report.


What to Submit

Your source code (contained in an .asm file)


a PDF file containing your typed write-up


Errata

This section of the assignment will be updated as changes and clarifications are made. Each entry here should have a date and brief description of the change so that you can look over the errata and easily see if any updates have been made since your last review.

Feb 24th - Posted documentation for final project.

TSA Project



Criteria
Ratings
Pts







Student submitted a .asm file with the source code and a .pdf file containing the typed project report.
10 pts
0 pts










Full
No
10 pts



Marks
Marks














All procedures contain a header that follows the format discussed during lecture.
6 pts
0 pts










Full
No
6 pts



Marks
Marks














Code is written according to the standards that have been explained thoughout the term (proper indentation, suitable
8 pts
0 pts


comments, easy to understand, etc).





Full
No
8 pts









Marks
Marks














Your code must be modularized into at least 4 procedures (not including main).
8 pts
0 pts










Full
No
8 pts



Marks
Marks





















enters correct mode based on value that is contained within the dereferenced DWORD variable (passed by




Code

4 pts
0 pts


OFFSET).





Full
No
4 pts














Marks
Marks














Student code is written in such a way that all features are available solely by pushing parameters onto the stack and calling
5 pts
0 pts


the "compute" procedure.





Full
No
5 pts









Marks
Marks
















Criteria
Ratings
Pts







Punctuation, spacing, and non-lowercase letters within plaintext are left intact by the encryption & decryption process.
3 pts
0 pts










Full
No
3 pts



Marks
Marks














Decoy mode functionality: Utilizes 3 parameters from the stack (as shown in the documentation): two 16 bit *signed*
4 pts
0 pts


WORD operands and a 32 bit OFFSET of a DWORD variable.





Full
No
4 pts









Marks
Marks














Decoy mode functionality: Code enters decoy mode by derefencing the OFFSET of a DWORD value (the last operand
3 pts
0 pts


pushed onto the stack) and verifying that the value is not -1 or -2. If you specifically check for the value 0, that's okay as





Full
No
3 pts

well.





Marks
Marks



















Decoy mode functionality: Code correctly sums the two signed 16 bit operands and stores the sum into the DWORD at the
5 pts
0 pts


provided OFFSET.





Full
No
5 pts









Marks
Marks


























Encryption mode functionality: Utilizes 3 parameters from the stack (as shown in the documentation): OFFSET of a BYTE
3 pts
0 pts


array (containing the 26 character key), OFFSET of BYTE array containing a NULL-terminated message, and OFFSET of





Full
No
3 pts






DWORD memory variable that contains the value -1.





Marks
Marks














Encryption mode functionality: Code utilizes the key (provided via OFFSET on the stack) and correctly encrypts the
14 pts
0 pts


message (also provided via OFFSET on the stack).





Full
No
14 pts









Marks
Marks















Criteria
Ratings
Pts






Encryption mode functionality: After execution of the procedure, each character of the plaintext array (inside the array) has
5 pts

0 pts

been replaced with its corresponding encrypted character.





Full

No
5 pts








Marks

Marks













Decryption mode functionality: Utilizes 3 parameters from the stack (as shown in the documentation): OFFSET of a BYTE
3 pts

0 pts

array (containing the 26 character key), OFFSET of BYTE array containing a NULL-terminated encrypted message, and





Full

No
3 pts
OFFSET of DWORD memory variable that contains the value -2.





Marks

Marks













Decryption mode functionality: Code utilizes the key (provided via OFFSET on the stack) and correctly decrypts the
14 pts

0 pts

encrypted text (also provided via OFFSET on the stack).





Full

No
14 pts








Marks

Marks













Decryption mode functionality: After execution of the procedure, each character of the encrypted text (inside the array) has
5 pts

0 pts

been replaced with its corresponding plaintext character.





Full

No
5 pts








Marks

Marks




















report is written professionally (with correct grammar and spelling).




Project

7.5 pts

0 pts









Full

No
7.5 pts


Marks

Marks













Report includes thoughtful answers to all 5 questions that are listed in the "project write-up" section of the documentation.
17.5 pts

0 pts









Full

No
17.5 pts


Marks

Marks














Criteria
Ratings
Pts




Extra credit: Successfully guess the grader (1 pt)
0 pts
0 pts






Full
No
0 pts

Marks
Marks









Extra credit (MUST be documented in the report): (2 pts) Decoy mode handles any combination of signed 16 bit operands
0 pts
0 pts

and returns the correct 32 bit signed sum (stored into the appropriate memory address).




Full
No
0 pts





Marks
Marks









Extra credit for key generation mode (MUST be documented in the report): (3 pts) Utilizes 2 parameters from the stack (as
0 pts
0 pts

shown in the documentation): OFFSET of a BYTE array (containing space for exactly 26 characters), and the OFFSET of a




Full
No

DWORD memory variable that contains the value -3. Places a randomly generated key into the provided array.




Marks
Marks
0 pts









Extra credit for key generation mode (MUST be documented in the report): (1 pt) Characters in key are random each time
0 pts
0 pts

the procedure is called (utilizing the Irvine random number procedure). (2 pts) The random number generator must be




Full
No
0 pts
properly seeded using Randomize.




Marks
Marks


























Extra credit for key generation mode (MUST be documented in the report): (2 pts) Generated key contains all 26 characters
0 pts
0 pts

of the English alphabet (stored into the provided array).




Full
No
0 pts







Marks
Marks











Deduction: (-10 pts) Global variables are not allowed within your procedures. They must operate correctly without any
0 pts
0 pts

".data" segment.




Full
No
0 pts







Marks
Marks













Criteria
Ratings
Pts







Deduction: (-5 pts) Within your procedures, only memory from the stack is utilized (registers are permitted of course).
0 pts
0 pts










Full
No
0 pts



Marks
Marks














Deduction: (-3 pts) Code must not corrupt the NULL character that is present at the end of each plaintext or encrypted
0 pts
0 pts


message.





Full
No
0 pts









Marks
Marks














Deduction: (-6 pts) Code must not impose any arbitrary length on the encrypted or decrypted message. The program must
0 pts
0 pts


function with messages that are up to 50,000 bytes in length (including the NULL character).





Full
No
0 pts









Marks
Marks














Deduction: (-3 pts) Code must treat the key as a 26 character array and should not require a NULL terminator to function
0 pts
0 pts


correctly.





Full
No
0 pts









Marks
Marks


























Deduction: (-10 pts) Code does not crash, halt abruptly, or enter any infinite loops.
0 pts
0 pts










Full
No
0 pts









Marks
Marks














Deduction: (-10 pts) The code does not corrupt any memory or produce unexpected output.
0 pts
0 pts










Full
No
0 pts



Marks
Marks














Criteria
Ratings
Pts




Deduction: (-2 pts) Your code should accept parameters from the stack in the exact order that is demonstrated in the
0 pts
0 pts

project documentation.




Full
No
0 pts





Marks
Marks









Late Penalty Remove points here for late assignments. (-50 pts per day)
0 pts
0 pts






Full
No
0 pts

Marks
Marks










Total Points: 125