Introduction The goal of this assignment is to gain practice

Introduction

The goal of this assignment is to gain practice with some important Python and computer science concepts:

reading and understanding algorithms (this can be quite a bit of work!)

understanding a top-down design

composing multiple functions that together implement the algorithm

working with strings and lists

We decided to write a main program that is separate from the set of helper functions that the main program uses.

You\'ll be implementing a program to encrypt and decrypt text using an encryption algorithm. Such an algorithm describes a process that turns plaintext into what looks like gibberish (we\'ll call this ciphertext), and decrypts the ciphertext back into plaintext. For example, your program will be able to take a secret message written in ciphertext, and figure out what it says. ... Like:
XHXZCHRYTMWEHOPPB
Hmmm. How can that ciphertext be decrypted, and what does it say? You\'ll have to do the assignment to find out!

The Encryption Algorithm

The encryption algorithm carries out encryption and decryption using a deck of cards^[1]. However, we\'re going to make two simplifications to a regular card deck. First, rather than use a standard deck of 52 cards, we\'re going to use 28 cards. Second, rather than use actual card ranks and suits, we\'re going to use the numbers from 1 to 28. We will call 27 and 28 the jokers. We\'re doing this because it\'s not necessary to know anything about playing cards to understand this algorithm, so we might as well use integers rather than card names.

We\'ll be doing lots of rounds, one for each letter in a message, and so we decided to have a function that does all the steps in a round.

Each of the steps in a round is independent, and so we decided to have a separate function for each step.

The algorithm is an example of a stream cipher. What that means is that every time you complete a round of the algorithm, you get one keystream value. This stream of values is then used, in combination with plaintext or ciphertext, to encrypt or decrypt, respectively. You will complete one round of the algorithm for each letter in the text to be encrypted or decrypted.

Each round of the algorithm consists of (one or more repetitions of) five steps; once all steps in a round are complete, one keystream value is available and the next round of keystream generation can begin.

Here is the algorithm; an example follows.

Begin with a deck of cards, which is really just a permutation of the integers from 1 to 28. The steps for one round are as follows:

Steps 1 and 2 involve swapping cards, so we\'ll have a helper function that does that; both step 1 and step 2 will call that function.

Find the card with value 27. Swap this card with the following card (so that it moves down one position). If the card with value 27 is at the bottom end of the deck, then swap the 27 with the top card. That is, think of the deck as circular, so that the card following the bottom card is the top card.

Find the card with value 28. Move it two cards down by performing two swaps, again treating the deck as circular.

Recall that the two cards with values 27 and 28 are the two jokers. Swap the cards above the first joker (the joker closest to the top of the deck) with the cards below the second joker. This is called a triple cut. Think about what happens if a joker is at the top or bottom of the deck? What if the jokers are next to each other? Is this a problem?

Look at the bottom card from the deck. That card will have some value v. If v is 28, use a value v of 27 in this step. Then, take v cards from the top of the deck, and put them above the bottom-most card in the deck.

If we get a joker as a potential keystream value, we might have to repeat all these steps. We decided to have a function that generates the next potential keystream value, and a separate function that calls that one until a non-joker is produced.

Look at the top card from the deck. That card will have some value v. If v is 28, use a value v of 27 in this step. Starting from the top, find the card that is at position v in the deck (the topmost card is at position 0). If the card on which you land is a joker, continue the current round at step 1. Otherwise, remember the value of the card on which you landed; this is the keystream value generated for the current round. This keystream value will be in the range 1-26 inclusive. (Thought question: why can\'t it be a 27 or a 28?)

To generate another keystream value, we take the deck as it is after step 5 and run another round of the algorithm. We need to generate one keystream value for each character in the text to be encrypted or decrypted.

Example: Completing one Round

Let\'s go through an example of how the algorithm generates keystream values. Consult the descriptions of the steps given above as you follow along with this example. We\'ll illustrate the first round of the algorithm, but encourage you to do another round by-hand so you really understand what\'s happening.

Consider the following deck. The top card has value 1. The bottom card has value 26.

Step 1: Swap 27 with the value following it. So, we swap 27 and 2:

Step 2: Move 28 two places down the list. It ends up between 6 and 9:

Step 3: Do the triple cut. Everything above the first joker (28 in this case) goes to the bottom of the deck, and everything below the second (27) goes to the top:

Step 4: The bottom card is 6. The first 6 cards of the deck are 5, 8, 11, 14, 17, and 20. They go just ahead of 6 at the bottom end of the deck:

Step 5: The top card is 23. Thus, our generated keystream value is the card at position 23. This card has value 11. Since this value 11 isn\'t 27 or 28, we are done with the round.

As a self-test, you should carry out the next round of the algorithm to find the second keystream value. Its value is 9; be sure you get the same value to convince yourself that you understand the five steps.

Encrypting and Decrypting

We\'ll be cleaning a lot of these messages to remove non-letters and converting to uppercase, so we decided to have a function for that.

We also are encrypting a single letter at a time, so we decided to have a function for that. Same for decryption.

To encrypt a message, remove all non-letters from the message and convert any lowercase letters to uppercase. Next, convert the letters to numbers (A becomes 0, B becomes 1, ..., Y becomes 24, and Z becomes 25). Then, use the algorithm to generate the same number of values as there are letters in the message. Add the corresponding pairs of numbers, modulo 26. Finally, convert the resulting numbers back to letters.

Decryption is just the reverse of encryption. Start by converting the message to be decoded to numbers. Using the same card ordering as was used to encrypt the message, generate one keystream value for each character in the message. (Because the same starting deck of cards was used, the same keystream will be generated.) Subtract the keystream values from the message numbers, again modulo 26. Finally, convert the numbers to letters to recover the message.

Example: Encrypting and Decrypting

Let\'s say we want to encrypt the message Lake Hylia. Removing non-letters and capitalizing the letters gives us LAKEHYLIA. Next, convert these letters to numbers:

Since we have nine letters, nine keystream values are required. Rather than go through nine rounds of the algorithm here, let\'s just assume that the nine generated keystream values are as follows:

Now add the two groups together pairwise, modulo 26. This means that if the sum of a pair is greater than 25, just subtract 26 from it. (For example, 1 + 8 = 9, but 11 + 17 = 28 - 26 = 2.) Then, convert these numbers to letters to arrive at the encrypted message:

To decrypt this message, the recipient would start with the same deck with which the encryption was started, and generate the same nine-number keystream. They would then convert the encrypted message to numbers. Then, instead of adding corresponding numbers from the keystream and message, they would pairwise-subtract the keystream from the message, modulo 26. That is, if the subtraction gives you a negative number, add 26 to the result. (For example, 9 - 8 = 1, and 2 - 17 = -15, but since it is negative you add -15 + 26 = 11.) The decryption back to LAKEHYLIA looks like this:

Of course we can never get all the way back to Lake Hylia because we don\'t know how to restore any lowercase letters or where to insert any spaces.

Files to Download

Please download the Assignment 1 Data Files and extract the zip archive. The following paragraphs explain the files you have been given.

The main program: cipher_program.py

This file contains the definition of three constants, an empty function called main, and a call on function main. More on this later.

A nearly-empty file: cipher_functions.py

You\'ll write almost all of the functions here. It\'s imported by cipher_program.py. It includes two constants: JOKER1 and JOKER2. In order to make your code more readable, use these constants instead of using 27 and 28lest you incur the wrath of the people marking your program!

deck files: deck1.txt and deck2.txt

We decided to store a deck in a text file, so we\'ll have a function that reads a deck file and builds a list of integers.

A deck of cards will be represented in Python as a list of numbers. We provide a sample deck in deck1.txt. Notice that this file has multiple lines: a deck file can have any number of lines. Another sample file deck2.txt is a different file, but if you look closely you will notice that it represents the same deck. Your function for reading in a deck must work for both these deck files and any others that we might use for testing. In particular, the numbers might be in a different order and there could be one or more numbers on each line.

Some message files: message-encrypted.txt, message-decrypted.txt and secret?.txt

We decided to store messages in text files, so we\'ll have a function that reads a message file and builds a list of strings.

Messages to encrypt or decrypt will be stored in text files. Message text files contain one message per line. Imagine that we\'re encrypting or decrypting a message file that contains multiple lines (i.e. multiple messages). The first line is encrypted (or decrypted) using the deck in the configuration as specified in a deck file. Subsequent lines of that same file are encrypted (or decrypted) starting with the configuration of the deck following the previous encryption (or decryption). That is, the deck is not reset between message lines of a message file.

We need to process a list of messages, so we decided to have a function that does this. We also decided to have a helper function that processes a single message.

The starter code archive contains a pair of text files: message-encrypted.txt and message-decrypted.txt that contain both an encrypted and decrypted version of the same message, and several other files named secret?.txt (secret1.txt, secret2.txt, etc.) containing ciphertext that you can decrypt. Some of them contain multiple messages, one message per line. They were all encrypted using the deck in deck1.txt.

A type-checking file: typechecker.py

To help you test, we provide a type checker. This program calls all of the functions that appear in the table below (except for function main and the two file-reading functions) and makes sure that your functions accept the proper number of parameters and return the proper type. Passing the type-checker says nothing of the correctness of your functions. It only says that your functions have the correct number of parameters and that the functions return the right type of value.

For example, if your clean_message function has one parameter and always returns the empty string, it will pass the type checker even though it is completely incorrect. Passing the type checker means that our own tests will be able to call your functions properly when we go mark your assignment. That\'s all it means. Test carefully on your own as explained more toward the end of this handout!

Solution

Follow the function design recipe we have been using in class. We will mark your docstrings in addition to your code, so we expect the docstrings to contain a description, examples, and type contract. Wrath of the markers and all that. We will be testing and marking each of these functions individually. So even if you can\'t complete the entire program and correctly encrypt and decrypt messages, you can earn marks for correctly implementing many of the function We present them in what we think is a sensible order, but you\'re welcome to jump around as you work. Notice that the functions near the top of the table don\'t require you to use lists or to read from a file.